Asynchronous Exports

Request custom advertising performance exports and download them as Parquet files.

Asynchronous Exports is available on Topsort’s public API. Use an Advanced API key to call it.

Asynchronous Exports lets you request a custom slice of your advertising performance data, choosing the dimensions and metrics you need for a time window, and receive it as a single Parquet file. Exports run in the background, so a large request never ties up a connection: you ask for the export, check on it, and download the file once it is ready.

How it works

1. Discover what you can export

   List the available datasets to see, for each one, the dimensions and metrics you can request, the dimensions the time window filters on, and the granularities you can ask for (how rows are grouped in time).

2. Request an export

   Choose a dataset, the dimensions to group by, the metrics to include, the granularity, and a time window of up to 31 days, starting no more than 120 days ago. Topsort validates the request and returns an export ID right away. Each export counts toward your daily quota.

3. Check its status

   The export moves from pending to running while Topsort builds the file. Check it every minute or so until it is completed or failed.

4. Download the file

   A completed export includes a secure download link to its Parquet file. The link is valid for 1 hour from the moment it is delivered, when you get the export status. Check the export again to get a new one.

Export lifecycle

Status	Meaning
pending	The request was accepted and is waiting to be processed.
running	Topsort is building the file.
completed	The file is ready to download.
failed	The export could not be produced. The response explains why.

Most exports finish in less than an hour. Failed exports are not retried automatically; request a new export instead.

Choosing the time window

• Days are in your local time: the data is grouped by day_local, and the window selects those local days.
• The window is set by a startDate and an endDate in YYYY-MM-DD format, both inclusive. To export the whole of September, start at 2026-09-01 and end at 2026-09-30. To export a single day, send the same date as both.
• The end must be on or after the start, and the window can cover up to 31 days, counting both the start and the end.
• The start can be up to 120 days before today (in UTC). Older data cannot be exported; the error tells you the earliest start date you can use.
• If the window includes today, keep in mind that today’s numbers can still be updated later.

Available data

The dataset, dimensions and metrics below are the ones available today. More may be added over time; the GET /export-service/datasets endpoint always returns the current list.

Monitoring metrics

The monitoring_metrics dataset covers advertising performance by campaign, placement and device, grouped into local days.

Dimensions (what each row is grouped by):

Group	Dimensions
Time	day_local
Account	currency_code
Vendor	vendor_id, external_vendor_id, vendor_name
Campaign	campaign_id, external_campaign_id, campaign_name, campaign_type, status, is_active, ad_format, charge_type
Promoted entity	entity_type, entity_id
Where the ad was seen	device_type, page_id, page_type, page_value, placement_page
Auction context	auction_device, auction_location, auction_page_type, auction_page_id, auction_page_value, auction_search_query, auction_category

Metrics (what each row adds up):

Group	Metrics
Delivery	impressions, clicks, charged_impressions, charged_clicks
Sales	purchase_count, quantity, total_purchase_amount, charged_attributed_purchases
Spend	ad_spend, ad_spent_clicks, ad_spent_impressions, ad_spent_exclusive_campaign, ad_spent_attributed_purchases
Ratios	ctr, conversion_rate, cpc, cpm, roas, acos

Monetary values are in your currency, reported in the currency_code dimension. See the Glossary for metric definitions.

The export file

• Format: one Parquet file per export.
• Columns: one per requested dimension, then one per requested metric, in the order you asked for them, named exactly as requested.
• Types: day_local is a calendar date (the local day), is_active is a boolean, other dimensions are text, and every metric is a decimal number.
• Rows: one per combination of the requested dimensions that had activity in the window.

Limits

Limit	Value
Granularity	day_local only: one row per local day
Time window	Up to 31 days per export, counting both the start and the end date
History	The start date can be up to 120 days before today (UTC)
Daily exports	20 per day by default; the quota resets at midnight UTC
Format	Parquet
Download link	Valid for 1 hour from the moment the link is delivered (when you get the export status); check the export again for a new link
File size	Up to 1 GiB; narrow the window or the dimensions if an export fails for size

Why was my request rejected?

Every error includes a stable code you can handle in your integration, a readable message and, when useful, details with more context.

code	What it means	What to do
daily_request_limit_exceeded	You used today’s quota	Wait until resetsAt (midnight UTC), shown in details
duplicate_dimension, duplicate_measure	A dimension or metric was sent twice	Send each value once
invalid_date_range	The end date is before the start date	Fix the window
date_range_too_large	The window is longer than 31 days	Split it into several exports
date_range_too_old	The start date is more than 120 days ago	Start on or after earliestDate, shown in details
validation_error	The request is malformed: a missing field, an unknown dataset, dimension, metric or granularity, or a date that is not in YYYY-MM-DD format	Check details for the field to fix
export_not_found	No export with that ID exists	Check the export ID
internal_error	Something went wrong on our side	Contact our customer support team

Frequently Asked Questions

My download link stopped working. Links expire 1 hour after they are delivered, when you get the export status. Check the export again to get a new link.

Can I get hourly, weekly or monthly rows? Not yet: day_local is the only granularity.

Can I export more than 31 days? Split the period into several exports of up to 31 days each, keeping your daily quota in mind.

Can I export data older than 120 days? No. The start date can be at most 120 days before today.

When do my 20 daily exports come back? All at once, at midnight UTC. The count is per UTC calendar day, not 24 hours after each request.

Can I filter by vendor or campaign? Not yet. Today an export is filtered by time window; include vendor_id or campaign_id as dimensions and filter the file after downloading it.

Can I get CSV instead of Parquet? Parquet is the only format we support.

---

For endpoints, request examples and error handling, see the Asynchronous Exports integration guide.