> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /public/v1/export-service/exports openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. - name: Placement API description: Placement management API for sponsored brand slots. - name: Export API description: Request an asynchronous Parquet export of your performance data. paths: /public/v1/export-service/exports: post: tags: - Export API summary: Create a data export description: |- 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. operationId: public_create_export requestBody: content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_PublicCreateExportRequest' required: true responses: '201': description: >- Your export was accepted and is `pending`. Check it with the returned `exportId` until it is `completed` or `failed`. content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_CreateExportResponse' '400': description: >- The request breaks an export rule. `detail` says which: a repeated dimension or metric, an end date before the start date, a window longer than 31 days, or a start date more than 120 days ago. '422': description: >- The request does not match the schema (`validation_error`): a missing field, an empty list, an unknown dataset, dimension, metric or granularity, a date that is not `YYYY-MM-DD`, or an export id that is not a UUID. `details` names the field to fix. content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_ExportServiceErrorResponse' '429': description: >- You reached your daily export limit (`daily_request_limit_exceeded`). The `Retry-After` header holds the seconds until the quota resets. headers: Retry-After: description: Seconds until the daily export quota resets. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_ExportServiceErrorResponse' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_PublicCreateExportRequest: properties: dataset: $ref: '#/components/schemas/Advanced_APIs_ExportDataset' description: >- The dataset to export. The datasets endpoint lists the ones you can request. examples: - monitoring_metrics dimensions: items: $ref: '#/components/schemas/Advanced_APIs_ExportPublicDimension' type: array maxItems: 27 minItems: 1 title: Dimensions description: >- 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. examples: - - day_local - vendor_id - campaign_id metrics: items: $ref: '#/components/schemas/Advanced_APIs_ExportMetric' type: array maxItems: 19 minItems: 1 title: Metrics description: >- Metrics to include in each row; each one becomes a column in the file. Send each value once. examples: - - impressions - clicks - ad_spend - roas granularity: $ref: '#/components/schemas/Advanced_APIs_ExportGranularity' description: >- How the rows are grouped in time. It must be one of the dataset's `granularities`; today only `day_local` is supported, one row per local day. examples: - day_local startDate: type: string format: date title: Start date description: >- First local day to export (`YYYY-MM-DD`, inclusive). It can be at most 120 days before today in UTC. examples: - '2026-09-01' endDate: type: string format: date title: End date description: >- Last local day to export (`YYYY-MM-DD`, inclusive). It must be on or after `startDate`, and the window can cover up to 31 days counting both. examples: - '2026-09-07' type: object required: - dataset - dimensions - metrics - granularity - startDate - endDate title: PublicCreateExportRequest description: The data you want to export. Advanced_APIs_CreateExportResponse: properties: exportId: type: string format: uuid title: Exportid description: ID of your export. Use it to check the export's status. examples: - 218ad339-00cd-4e11-aeaa-8d96694908a0 status: $ref: '#/components/schemas/Advanced_APIs_ExportStatus' description: 'Always `pending`: your export starts in the background.' examples: - pending dataset: $ref: '#/components/schemas/Advanced_APIs_ExportDataset' description: The dataset being exported. examples: - monitoring_metrics createdAt: type: string format: date-time title: Createdat description: When you requested the export. examples: - '2026-09-08T14:03:12Z' type: object required: - exportId - status - dataset - createdAt title: CreateExportResponse description: The export you requested, which runs in the background. Advanced_APIs_ExportServiceErrorResponse: properties: error: $ref: '#/components/schemas/Advanced_APIs_ExportServiceError' description: 'What went wrong: a stable code, a message and its context.' type: object required: - error title: ExportServiceErrorResponse description: Error response. Advanced_APIs_ExportDataset: type: string enum: - monitoring_metrics title: ExportDataset description: >- Datasets you can export. The datasets endpoint lists what each one accepts. Advanced_APIs_ExportPublicDimension: type: string enum: - 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 - external_vendor_id - vendor_name - campaign_name - external_campaign_id - status - campaign_type - ad_format - charge_type - is_active title: ExportPublicDimension description: >- Dimensions you can group an export by; each one becomes a column in the file. Advanced_APIs_ExportMetric: type: string enum: - 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 title: ExportMetric description: >- Metrics you can include in an export; each one becomes a column in the file. Advanced_APIs_ExportGranularity: type: string enum: - day_local title: ExportGranularity description: >- How export rows are grouped in time; `day_local` means one row per local day. Advanced_APIs_ExportStatus: type: string enum: - pending - running - completed - failed title: ExportStatus description: 'Export status: `pending`, then `running`, then `completed` or `failed`.' Advanced_APIs_ExportServiceError: properties: code: type: string title: Code description: >- Stable error code to handle in your integration (e.g. `validation_error`, `daily_request_limit_exceeded`). examples: - internal_error message: type: string title: Message description: Human-readable explanation of the error. examples: - An unexpected error occurred. details: items: additionalProperties: true type: object type: array title: Details description: >- More context about the error, empty when there is none. `validation_error` lists each invalid input with its `type`, its location (`loc`), a message (`msg`) and the value you sent (`input`). Duplicate and date errors name the `field` (and the repeated `members`). `daily_request_limit_exceeded` includes `limit`, `used`, `resetsAt` and `retryAfterSeconds`. `date_range_too_large` includes `days` and `maxDays`. `date_range_too_old` includes `earliestDate` and `maxDaysBack`. examples: - [] type: object required: - code - message title: ExportServiceError description: What went wrong with your request. securitySchemes: Advanced_APIs_HTTPBearer: type: http description: >- 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. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.