> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trackplay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Start an export

> Ask for a batch of analytics as a file. An export runs in the background, so this call returns straight away with an `export_id` and `status: pending`. Poll `GET /exports/{export}` until it is `ready`, then fetch the file from `download_url`.

One export can cover up to 50 videos.

Send an `Idempotency-Key` so a retried request returns the same export instead of starting a second one.

Requires a token with the `analytics:read` scope.

Server: `https://app.trackplay.io/api/v1`



## OpenAPI

````yaml /api-reference/openapi.json post /exports
openapi: 3.1.0
info:
  title: TrackPlay API
  description: >-
    Send conversions and events to TrackPlay, and read them back. Authenticated
    with scoped tokens you mint in the dashboard.
  version: 1.0.0
servers:
  - url: https://app.trackplay.io/api/v1
    description: App API. Conversions, videos, webhooks.
  - url: https://e.trackplay.io
    description: Events API. High-volume event ingest.
security:
  - bearerAuth: []
paths:
  /exports:
    post:
      tags:
        - Exports
      summary: Start an export
      description: >-
        Ask for a batch of analytics as a file. An export runs in the
        background, so this call returns straight away with an `export_id` and
        `status: pending`. Poll `GET /exports/{export}` until it is `ready`,
        then fetch the file from `download_url`.


        One export can cover up to 50 videos.


        Send an `Idempotency-Key` so a retried request returns the same export
        instead of starting a second one.


        Requires a token with the `analytics:read` scope.


        Server: `https://app.trackplay.io/api/v1`
      operationId: createExport
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Retry-safe key. The first response for a given key is cached for 24
            hours and replayed on a repeat, with `Idempotency-Replayed: true`
            set.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportRequest'
            examples:
              events:
                summary: Export raw events for two videos as CSV
                value:
                  video_ids:
                    - 481
                    - 482
                  from: '2026-06-17'
                  to: '2026-07-17'
                  format: csv
                  type: events
      responses:
        '202':
          description: >-
            Accepted. The export is queued. Poll its status to get the download
            link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCreatedResponse'
              examples:
                pending:
                  value:
                    export_id: tpex_9f2c1a7e4d3b4a11
                    status: pending
        '401':
          description: >-
            `AUTH_REQUIRED`: no token sent. `INVALID_TOKEN`: the token is
            invalid, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: '`INSUFFICIENT_SCOPE`: the token does not carry `analytics:read`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: One or more of the `video_ids` do not exist in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                not_found:
                  value:
                    error:
                      code: VIDEO_NOT_FOUND
                      message: One or more video IDs not found.
        '422':
          description: >-
            Validation failed. Check `video_ids` holds 1 to 50 IDs, `to` is on
            or after `from`, and `format` and `type` are one of the allowed
            values.
        '429':
          description: Rate limited. Reads are capped at 600 requests per minute per token.
components:
  schemas:
    ExportRequest:
      type: object
      required:
        - video_ids
        - from
        - to
        - format
        - type
      properties:
        video_ids:
          type: array
          items:
            type: integer
          minItems: 1
          maxItems: 50
          description: >-
            The videos to export. Between 1 and 50 IDs. Every ID must exist in
            this workspace.
        from:
          type: string
          format: date
          description: Start of the range, as an ISO date. Required.
        to:
          type: string
          format: date
          description: >-
            End of the range, as an ISO date. Must be on or after `from`.
            Required.
        format:
          type: string
          enum:
            - csv
            - json
          description: The file format. Required.
        type:
          type: string
          enum:
            - events
            - summary
            - retention
            - conversions
          description: Which dataset to export. Required.
    ExportCreatedResponse:
      type: object
      properties:
        export_id:
          type: string
          description: >-
            The export's ID, e.g. `tpex_9f2c1a7e4d3b4a11`. Poll it to get the
            download link.
          examples:
            - tpex_9f2c1a7e4d3b4a11
        status:
          type: string
          description: Always `pending` at this point.
          examples:
            - pending
    ApiError:
      type: object
      description: The error shape the app API returns on a failed read or export.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                A stable error code, e.g. `INSUFFICIENT_SCOPE`,
                `VIDEO_NOT_FOUND`, `EXPORT_NOT_FOUND`.
            message:
              type: string
              description: What went wrong, in plain English.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A scoped token minted in **Settings → API tokens**. Send it as
        `Authorization: Bearer tplt_…` or `X-API-Key: tplt_…`.

````