Amazon S3 File Storage and History

This guide explains how Adzviser names S3 export files, what happens when a file is written again, and how to retain earlier versions.

To connect your bucket, start with Set up the connection.

File layout

An S3 object key is the file's full path inside your bucket. For a typical daily export, the layout is:

[path-prefix/]<workspace>/<data-source>/<reporting-date>/<file-label>.csv

JSON exports use the same layout with a .json extension. Path Prefix is optional. The workspace and data-source folders use their names, with any / characters replaced by _.

Rows are grouped by the first column of the exported table, usually the reporting date. If that column contains another value, that value is used as the folder name instead; any / characters in it become -. The folder therefore reflects the exported data, not when the pipeline ran.

The file label is the data-source name with spaces removed, such as GoogleAds. When a source returns separate report segments, the segment name is appended, such as GoogleAds_campaign. Spaces are removed from segment names, and / becomes _.

For example, with bucket marketing-exports, prefix adzviser, workspace Acme, and source Google Ads, a daily campaign report could write:

s3://marketing-exports/adzviser/Acme/Google Ads/2026-09-24/GoogleAds_campaign.csv
s3://marketing-exports/adzviser/Acme/Google Ads/2026-09-25/GoogleAds_campaign.csv

The usual path contains no pipeline name, run ID, or execution timestamp. If a table with only headers is written, its fallback folder uses start-date_to_end-date when both dates are supplied, or an execution timestamp otherwise. This fallback does not create a separate historical file for every run.

Rerunning an export

If you export September 25 again with the same bucket, prefix, workspace, source, report segment, and format, Adzviser writes to the same September 25 path shown above. The new file contains the data returned by that export; rows are not appended to the existing file. In an unversioned bucket, the previous contents at that path are replaced.

This applies to scheduled runs, manual runs, retries, and backfills with overlapping dates. Changing the selected accounts, metrics, or pipeline name does not automatically give the export a new path. Two pipelines that produce the same path can replace each other's files. Use separate destination prefixes or buckets when their outputs need to stay separate.

Only the paths written by a run are updated. Files for dates or segments absent from that run remain in the bucket; an export does not clear the folder or synchronize deletions.

The Export History tab records runs and their results. It does not keep a separate copy of each run's files or link runs to specific S3 version IDs.

Retaining earlier versions

To retain earlier contents when the same path is written again, your AWS administrator can enable S3 Versioning on the destination bucket:

1. In the S3 console, open your bucket and choose Properties.
2. Under Bucket Versioning, choose Edit > Enable > Save changes.
3. When enabling it for the first time, follow AWS's recommendation to wait 15 minutes before exporting again. See AWS's versioning setup instructions.

With versioning enabled, S3 retains each write as a version of the same object key, and the latest version is the current file. Enabling it cannot recover contents already overwritten in an unversioned bucket. Review lifecycle rules that expire older versions and allow for the storage cost of retained versions. How S3 Versioning works.

Versioning alone does not guarantee an immutable archive. Authorized deletion and lifecycle rules can remove older versions. If you need versions protected against deletion for a retention period, have your AWS administrator configure and verify an appropriate S3 Object Lock retention arrangement.

Adzviser does not enable these bucket settings or create an immutable snapshot of each pipeline execution. S3 versions track individual file writes; a complete archive tied to each run requires a separate archival workflow or a product change.