Amazon Ads report formats: JSON, CSV and Parquet compared

In short: Amazon Ads reports are delivered as files in named formats. Reporting API v1 and exports deliver JSON compressed in gzip format. Reports include performance data such as impressions or clicks. Exports contain campaign metadata such as budget or status. Amazon Marketing Stream v2 writes Parquet to S3, AMC outputs CSV.

Which formats Amazon uses for reports and exports

The question "amazon ads to json" comes up because an advertiser wants to pull a file out of the advertising account and load it into their own system. Amazon delivers the files in different formats depending on the surface, and the answer depends on which surface you use.

For reporting API v1 and the exports API the rule is: the file is delivered as JSON compressed in gzip. That holds for reports (performance data) as well as for exports (campaign metadata). A report contains metrics such as impressions, clicks or conversions, an export contains metadata such as budget or status. Amazon recommends requesting metadata through the export resource because that improves performance.

Amazon Marketing Stream version 2 no longer writes JSON files; it writes Apache Parquet files into your S3 bucket. Version 1 of the stream still delivered JSON over Firehose or SQS, but it shuts off on June 30, 2027 together with reporting API v3 and version 2 reporting for sponsored ads.

Amazon Marketing Cloud itself outputs results as CSV: a workflow produces a file suffixed with -ver1.csv and places it in your S3 bucket or serves it through a download URL.

SurfaceFile formatContent
Reporting API v1JSON in gzip (GZIP_JSON, also PARTITIONED_GZIP_JSON)Performance data: metrics per dimension
Exports APIJSON in gzipCampaign metadata such as budget or status
Amazon Marketing Stream v2Apache Parquet in S3Complete datasets, every 15 minutes
Amazon Marketing Stream v1 (legacy)JSON over Firehose or SQSDelta messages, shuts off 2027
Amazon Marketing CloudCSV (-ver1.csv)SQL result of your query

The formats are not accidental: JSON in gzip is the exchange format of the Ads API because it maps every nested structure and compresses well. Parquet is the columnar format for data you want to query inside AWS because it is partitioned and read column by column. CSV is the result format of AMC because SQL results are tabular.

How to load an Amazon Ads file as JSON

Anyone pulling a file out of the Ads API runs through the same asynchronous flow: submit the request, wait for completion, download the file. The difference between a report and an export is the content, not the flow.

When you convert JSON into another format

The most common reason for the search is not the download but the downstream processing: the tool at the end of the chain takes CSV or Parquet, not JSON in gzip. The conversion is then a step in the pipeline, not an Amazon feature.

Two cases are typical. First BI tools: Excel, Power BI or Looker Studio read CSV, not gzip-JSON. Second AWS queries: Athena or Glue read Parquet directly, but gzip-JSON only through extra steps. Anyone subscribing to Marketing Stream v2 gets Parquet and needs no conversion for AWS queries.

What Amazon does not ship is a switch that outputs reporting API v1 results directly as CSV or Parquet. The formats PARTITIONED_GZIP_JSON and PARTITIONED_CSV of reporting API v1 only split large reports into files; the format stays JSON in gzip or CSV.

  • **BI tool at the end:** unpack the JSON in gzip, then convert it to CSV before the tool reads the file.
  • **Athena or Glue at the end:** subscribe to Marketing Stream v2 and query Parquet directly instead of converting JSON.
  • **AMC result at the end:** take the CSV from the workflow, it is already there.
  • **Add metadata:** join the export by ID to the report instead of repeating both data sets in the report.

Checklist: what has to be right before processing

Before the file runs into a dashboard or a model, check four points. They cost minutes and prevent silent errors in the analysis.

  • **Download URL:** it is valid for only one hour; download the file right after retrieval and do not store the URL long term.
  • **Empty rows:** a report without clicks or views can return an empty JSON array; check that before you read zeros into it.
  • **Refresh:** click data arrives earliest after 12 hours, conversions can be restated up to 60 days back; re-retrieve reports monthly.
  • **Concurrency:** reporting API v1 allows one report per client ID; spread requests across the day or you get a 429.

Step by step

  1. Request a report or an export. POST to the report or export endpoint with the desired fields; the response contains a reportId or exportId with status IN_PROGRESS.
  2. Poll the status. GET the status endpoint with the ID until the status reads COMPLETED. Amazon recommends polling a report about once per minute.
  3. Download and decompress the file. The download URL is valid for only one hour; the file is JSON in gzip, unpack it with gunzip and raw JSON is what you get.
  4. Load into the target system. Load the JSON rows into the target system, enrich them with metadata from the export by ID, and output the date as its own column so rows cannot be split by day later.

Frequently asked questions

Does Amazon Ads deliver reports directly as JSON?

Yes, but compressed: reports of reporting API v1 and the exports API are delivered as JSON in gzip. After unpacking with gunzip you have raw JSON. A direct download as uncompressed JSON or a CSV switch does not exist for reporting API v1.

Why does Marketing Stream deliver Parquet instead of JSON?

Because the stream is built for queries inside AWS: Parquet is a columnar format that can be partitioned and read column by column. Version 1 of the stream still delivered JSON over Firehose or SQS, version 2 delivers Parquet to S3 and thereby serves the use case of dashboards, optimization and modelling.

Are reports and exports the same format?

Both are delivered as JSON in gzip, but they carry different content. A report contains performance data such as impressions or clicks, an export contains campaign metadata such as budget or status. Amazon recommends requesting metadata through the export resource because that improves performance.

Are AMC results available as JSON?

No: Amazon Marketing Cloud outputs the result of a query as CSV, either as a -ver1.csv in the S3 bucket or through a download URL. Anyone who wants to load AMC results into a JSON-based system converts the CSV themselves in the pipeline.

When should I choose Marketing Stream over the reporting API?

When you want to write raw data into your own systems, build dashboards, run optimization logic or train models, Amazon recommends Marketing Stream v2: it delivers Parquet without polling and without throttling. For prepared stakeholder reports and periodic analysis the reporting API v1 is the fitting surface.

Sources: Amazon Ads API: Amazon Ads reporting overview · Amazon Ads API: Get started with exports · Amazon Ads API: Amazon Marketing Stream v2 overview · Amazon Ads API: New features of the reporting API v1 · Amazon Ads API: Get your AMC results · Amazon Ads API: Limits and best practices (retrieved 2026-11-17)

Keep reading: Amazon Ads Reporting · Results in Amazon S3 · AMC results in BI tools