Create a data export

Request an export of the dimensions and metrics you choose.

The file is generated in the background. Save exportId and check the export until it is completed or failed. Each accepted export counts toward your daily quota.

vendorIds is a filter, not access control: send it to export only those vendors, or leave it out to export every vendor. entityTypes narrows the export the same way.

POST /public/v1/export-service/exports

Create a data export

cURL

curl --request POST \
  --url https://api.topsort.com/public/v1/export-service/exports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset": "monitoring_metrics",
  "dimensions": [
    "day_local",
    "vendor_id",
    "campaign_id"
  ],
  "metrics": [
    "impressions",
    "clicks",
    "ad_spend",
    "roas"
  ],
  "granularity": "day_local",
  "startDate": "2026-09-01",
  "endDate": "2026-09-07",
  "vendorIds": [
    "vendor_123",
    "vendor_456"
  ],
  "entityTypes": [
    "product",
    "halo-product"
  ]
}
'

201

{
  "exportId": "218ad339-00cd-4e11-aeaa-8d96694908a0",
  "status": "pending",
  "dataset": "monitoring_metrics",
  "createdAt": "2026-09-08T14:03:12Z"
}

Autorisierungen

Authorization · string · header · erforderlich

A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key.

Body

application/json

The data you want to export.

dataset · enum<string> · erforderlich

The dataset to export. The datasets endpoint lists the ones you can request.

Verfügbare Optionen: monitoring_metrics

Beispiel:

"monitoring_metrics"

dimensions · enum<string>[] · erforderlich

Dimensions to group the rows by; each one becomes a column in the file. Send each value once. Columns appear in the order you send them: dimensions first, then metrics.

Required array length: 1 - 26 elements

Dimensions you can group an export by; each one becomes a column in the file.

Verfügbare Optionen: vendor_id, campaign_id, entity_type, entity_id, day_local, device_type, page_id, page_type, page_value, placement_page, auction_device, auction_location, auction_page_type, auction_page_id, auction_page_value, auction_search_query, auction_category, currency_code, vendor_name, campaign_name, external_campaign_id, status, campaign_type, ad_format, charge_type, is_active

Beispiel:

["day_local", "vendor_id", "campaign_id"]

metrics · enum<string>[] · erforderlich

Metrics to include in each row; each one becomes a column in the file. Send each value once.

Required array length: 1 - 19 elements

Metrics you can include in an export; each one becomes a column in the file.

Verfügbare Optionen: impressions, clicks, charged_clicks, charged_impressions, charged_attributed_purchases, quantity, purchase_count, ad_spent_clicks, ad_spent_impressions, ad_spent_exclusive_campaign, ad_spent_attributed_purchases, ad_spend, total_purchase_amount, ctr, conversion_rate, cpc, cpm, roas, acos

Beispiel:

["impressions", "clicks", "ad_spend", "roas"]

granularity · enum<string> · erforderlich

How the rows are grouped in time, one of the dataset's granularities. day_local gives one row per local day and adds day_local as the first column if dimensions leaves it out. total gives one row of totals for the whole window per combination of the other dimensions, so dimensions cannot include day_local.

Verfügbare Optionen: day_local, total

Beispiele:

"day_local"

"total"

startDate · string<date> · erforderlich

First local day to export (YYYY-MM-DD, inclusive). By default it can be at most 120 days before today in UTC; your limit may differ, and the error for an older date states it.

Beispiel:

"2026-09-01"

endDate · string<date> · erforderlich

Last local day to export (YYYY-MM-DD, inclusive). It must be on or after startDate, and by default the window can cover up to 31 days counting both; your limit may differ, and the error for a longer window states it.

Beispiel:

"2026-09-07"

vendorIds · string[]

The vendor_id of each vendor to export, up to 100. It only narrows the export and does not restrict access: leave it out or empty to export every vendor. An unknown ID rejects the request.

Maximum array length: 100

Required string length: 1 - 255

Beispiel:

["vendor_123", "vendor_456"]

entityTypes · enum<string>[]

The entity_type values to export. It only narrows the export: leave it out or empty to export every entity type.

Maximum array length: 4

Entity types you can filter an export by, as they appear in the entity_type column.

Verfügbare Optionen: halo-product, product, url, vendor

Beispiel:

["product", "halo-product"]

Antwort

201

application/json

Your export was accepted and is pending. Check it with the returned exportId until it is completed or failed.

The export you requested, which runs in the background.

exportId · string<uuid> · erforderlich

ID of your export. Use it to check the export's status.

Beispiel:

"218ad339-00cd-4e11-aeaa-8d96694908a0"

status · enum<string> · erforderlich

Always pending: your export starts in the background.

Verfügbare Optionen: pending, running, completed, failed

Beispiel:

"pending"

dataset · enum<string> · erforderlich

The dataset being exported.

Verfügbare Optionen: monitoring_metrics

Beispiel:

"monitoring_metrics"

createdAt · string<date-time> · erforderlich

When you requested the export.

Beispiel:

"2026-09-08T14:03:12Z"