Customer.io Exports API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Exports API
  description: Customer.io provides REST APIs to send real-time customer data, retrieve data from your account, and trigger messages.
servers:
- url: https://track.customer.io
  description: The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://track-eu.customer.io
  description: The base URL for the Track API (EU region). Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://api.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Exports
  description: Export information about people, deliveries, etc. You can also download existing exports from these endpoints.
paths:
  /v1/exports:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    get:
      summary: List exports
      operationId: listExports
      security:
      - Bearer-Auth: []
      description: Return a list of your exports. Exports are point-in-time people or automation metrics.
      tags:
      - Exports
      responses:
        '200':
          description: Returns an array of exports.
          content:
            application/json:
              schema:
                type: object
                properties:
                  exports:
                    type: array
                    items:
                      $ref: '#/components/schemas/exportObject'
        '429':
          $ref: '#/components/responses/429'
  /v1/exports/{export_id}:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - $ref: '#/components/parameters/export_id'
    get:
      summary: Get an export
      operationId: getExport
      security:
      - Bearer-Auth: []
      description: Return information about a specific export.
      tags:
      - Exports
      responses:
        '200':
          description: Returns an export.
          content:
            application/json:
              schema:
                type: object
                properties:
                  export:
                    $ref: '#/components/schemas/exportObject'
        '404':
          description: The export ID does not exist.
        '429':
          $ref: '#/components/responses/429'
  /v1/exports/{export_id}/download:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - $ref: '#/components/parameters/export_id'
    get:
      summary: Download an export
      operationId: downloadExport
      security:
      - Bearer-Auth: []
      description: This endpoint returns a signed link to download an export. The link expires after 15 minutes.
      tags:
      - Exports
      responses:
        '200':
          description: Returns a link to an export.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: url
                    description: A link to download your export. Expires after 15 minutes.
        '404':
          description: The export ID does not exist.
        '429':
          $ref: '#/components/responses/429'
  /v1/exports/customers:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    post:
      summary: Export customer data
      operationId: exportPeopleData
      security:
      - Bearer-Auth: []
      description: Provide filters and attributes describing the customers you want to export. This endpoint returns export metadata; use the `/exports/{export_id}/endpoint` to download your export.
      tags:
      - Exports
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - filters
              properties:
                filters:
                  $ref: '#/components/schemas/audienceFilter'
                attributes:
                  description: Recipient attributes you want to include as extra columns in your export.
                  type: array
                  items:
                    type: string
            example:
              filters:
                and:
                - segment:
                    id: 3
                - or:
                  - attribute:
                      field: interest
                      operator: eq
                      value: roadrunners
                  - attribute:
                      field: state
                      operator: eq
                      value: NM
                  - not:
                      attribute:
                        field: species
                        operator: eq
                        value: roadrunners
      responses:
        '200':
          description: Returns an export.
          content:
            application/json:
              schema:
                type: object
                properties:
                  export:
                    $ref: '#/components/schemas/exportObject'
        '400':
          description: The request is malformed.
        '429':
          $ref: '#/components/responses/429'
  /v1/exports/deliveries:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    post:
      summary: Export information about deliveries
      operationId: exportDeliveriesData
      security:
      - Bearer-Auth: []
      description: 'Provide filters for the one-time send, automation, or action you want to return delivery information from. This endpoint starts an export, but you cannot download your export from this endpoint. Use the `/exports/{export_id}` endpoint to download your export.


        Use the `start` and `end` to find messages within a time range. If your request doesn''t include `start` and `end` parameters, we''ll return the most recent 6 months of messages. If your `start` and `end` range is more than 12 months, we''ll return 12 months of data from the most recent timestamp in your request. Timestamps reflect when deliveries were created in our system, not when they were actually sent to recipients. There may be a delay between creation and sending.'
      tags:
      - Exports
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - title: Newsletter
                allOf:
                - type: object
                  required:
                  - newsletter_id
                  properties:
                    newsletter_id:
                      type: integer
                      description: The ID of a one-time send you want to export information from.
                      example: 999
                - $ref: '#/components/schemas/exportSharedProps'
              - title: Campaign
                allOf:
                - type: object
                  required:
                  - campaign_id
                  properties:
                    campaign_id:
                      type: integer
                      description: The ID of an automation you want to export information from.
                      example: 46
                - $ref: '#/components/schemas/exportSharedProps'
              - title: Transactional Message
                allOf:
                - type: object
                  required:
                  - transactional_message_id
                  properties:
                    transactional_message_id:
                      example: 22
                      type: integer
                      description: The ID of the transactional message you want to export information for.
                - $ref: '#/components/schemas/exportSharedProps'
              - title: Action
                allOf:
                - type: object
                  required:
                  - action_id
                  properties:
                    action_id:
                      example: 77
                      type: integer
                      description: The ID of an action you want to export information from.
                - $ref: '#/components/schemas/exportSharedProps'
      responses:
        '200':
          description: Returns an export.
          content:
            application/json:
              schema:
                type: object
                properties:
                  export:
                    $ref: '#/components/schemas/exportObject'
                example:
                  export:
                    id: 111,
                    deduplicate_id: 110:1530296738
                    type: deliveries
                    failed: false
                    description: Full deliveries export (created via the api)
                    downloads: 0
                    created_at: 1530296742
                    updated_at: 1530296742
        '400':
          description: The request is malformed.
        '429':
          $ref: '#/components/responses/429'
components:
  schemas:
    export_id:
      x-scalar-ignore: true
      type: integer
      description: The identifier for the export.
      example: 110
    start:
      x-scalar-ignore: true
      description: The unix timestamp representing the beginning of the export.
      type: integer
      format: unix timestamp
      example: 1517529600
    metric:
      x-scalar-ignore: true
      description: Determines the metric(s) you want to return.
      type: string
      enum:
      - created
      - attempted
      - sent
      - delivered
      - opened
      - clicked
      - converted
      - bounced
      - spammed
      - unsubscribed
      - dropped
      - failed
      - undeliverable
    notAudienceFilter:
      x-scalar-ignore: true
      title: not
      description: Returns people who don't match the condition inside it. `not` takes a single object, not an array. That object can be one condition, or an `and` or `or` group when you want to exclude people who match a combination of conditions.
      oneOf:
      - title: and
        type: object
        properties:
          and:
            type: array
            description: Match *all* conditions to return results.
            items:
              $ref: '#/components/schemas/complexAudienceFilter'
      - title: or
        type: object
        properties:
          or:
            type: array
            description: Match *any* condition to return results.
            items:
              $ref: '#/components/schemas/complexAudienceFilter'
      - title: segment
        type: object
        properties:
          segment:
            $ref: '#/components/schemas/segmentAudienceFilter'
      - title: attribute
        type: object
        properties:
          attribute:
            $ref: '#/components/schemas/attributeAudienceFilter'
    appApiError:
      x-scalar-ignore: true
      type: object
      description: An array/list of failures where each entry is a separate failure reason.
      required:
      - errors
      properties:
        errors:
          type: array
          description: One entry for each reason the request failed.
          items:
            type: object
            required:
            - detail
            - status
            properties:
              detail:
                type: string
                description: What went wrong, in plain text. Most messages end with a support reference you can use if you need to contact support.
                example: bad request (reference a1b2c3)
              status:
                type: string
                description: The HTTP status code as a string.
                example: '400'
              code:
                type: string
                description: A stable identifier for the failure, on the errors that carry one. Use this rather than the text in `detail` if you need to identify the error programmatically.
                example: invalid_credentials
              source:
                type: object
                description: The part of the request that the error refers to.
                properties:
                  pointer:
                    type: string
                    description: A JSON pointer to the part of the request body that the error refers to.
                    example: /data/attributes/email
              meta:
                type: object
                additionalProperties: true
                description: Extra context (if available).
    audienceFilter:
      x-scalar-ignore: true
      title: Audience Filter
      description: Use `and`, `or`, and `not` to combine segment and attribute conditions. The top-level object accepts one property; nest groups for complex filters.
      oneOf:
      - $ref: '#/components/schemas/andAudienceFilter'
      - $ref: '#/components/schemas/orAudienceFilter'
      - $ref: '#/components/schemas/notAudienceFilter'
      - title: segment
        description: Filter for people who belong to a segment.
        type: object
        properties:
          segment:
            $ref: '#/components/schemas/segmentAudienceFilter'
      - title: audience
        type: object
        description: filter for people who have an attribute or an attribute value.
        properties:
          attribute:
            $ref: '#/components/schemas/attributeAudienceFilter'
    exportObject:
      x-scalar-ignore: true
      type: object
      description: Metadata about an export.
      properties:
        id:
          $ref: '#/components/schemas/export_id'
        user_id:
          type: integer
          description: The user who created the export.
        user_email:
          type: string
          description: The email of the user who created the export.
        total:
          type: integer
          description: The number of entries in the export. Exports report 0 until done.
        deduplicate_id:
          $ref: '#/components/schemas/deduplicate_id'
        type:
          $ref: '#/components/schemas/export_type'
        failed:
          $ref: '#/components/schemas/export_failed'
        description:
          $ref: '#/components/schemas/export_description'
        downloads:
          $ref: '#/components/schemas/export_downloads'
        created_at:
          $ref: '#/components/schemas/created'
        updated_at:
          $ref: '#/components/schemas/updated'
        status:
          type: string
          enum:
          - done
          - pending
          - failed
          description: The state of your export where `done` indicates an export that you can download, `pending`, indicates that your export is not ready to download, and `failed` indicates an export that has failed and will not be downloadable.
      example:
        id: 110
        user_id: 0
        user_email: person@email.com
        total: 1234
        deduplicate_id: 110:1530296738
        type: customers
        failed: false
        status: done
        description: Customers with segment filters—in \Purchased Flowers\
        downloads: 2
        created_at: 1530296738
        updated_at: 1530296738
    updated:
      x-scalar-ignore: true
      type: integer
      format: unix timestamp
      description: The date time when the referenced ID was last updated.
      example: 1552341937
      readOnly: true
    deduplicate_id:
      x-scalar-ignore: true
      type: string
      readOnly: true
      description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Automations, Deliveries, Exports, Identities, One-time sends, Segments, and Templates), and the timestamp is the last time the object was updated.
      example: 15:1492548073
    end:
      x-scalar-ignore: true
      description: The unix timestamp representing the end of the export.
      type: integer
      format: unix timestamp
      example: 1517702400
    segmentAudienceFilter:
      x-scalar-ignore: true
      title: segment
      type: object
      description: Provide the `id` of a segment containing people you want to search for.
      properties:
        id:
          type: integer
          description: The ID of the segment you want to return people from.
          example: 4
        inverse:
          type: boolean
          default: false
          description: Set to `true` to match people who *aren't* in the segment.
    export_downloads:
      x-scalar-ignore: true
      type: integer
      description: Counts the total number of times the export has been downloaded.
      example: 2
    complexAudienceFilter:
      x-scalar-ignore: true
      title: People Filter
      type: object
      description: Filter people with `and`, `or`, and `not` groups made from `segment` and `attribute` conditions.
      properties:
        and:
          type: array
          description: Returns results matching *all* conditions.
          items:
            $ref: '#/components/schemas/simpleAudienceFilter'
        or:
          type: array
          description: Returns results matching *any* conditions.
          items:
            $ref: '#/components/schemas/simpleAudienceFilter'
        not:
          description: Returns people who don't match conditions. `not` takes a single object, not an array. That object can be one condition, or an `and` or `or` group when you want to exclude people who match a combination of conditions.
          oneOf:
          - title: and
            type: object
            properties:
              and:
                type: array
                description: Match *all* conditions to return results.
                items:
                  $ref: '#/components/schemas/simpleAudienceFilter'
          - title: or
            type: object
            properties:
              or:
                type: array
                description: Match *any* condition to return results.
                items:
                  $ref: '#/components/schemas/simpleAudienceFilter'
          - title: segment
            type: object
            properties:
              segment:
                $ref: '#/components/schemas/segmentAudienceFilter'
          - title: attribute
            type: object
            properties:
              attribute:
                $ref: '#/components/schemas/attributeAudienceFilter'
        segment:
          $ref: '#/components/schemas/segmentAudienceFilter'
        attribute:
          $ref: '#/components/schemas/attributeAudienceFilter'
    attributeAudienceFilter:
      x-scalar-ignore: true
      title: attribute
      description: Filter your audience by attribute.
      type: object
      required:
      - field
      - operator
      properties:
        field:
          type: string
          description: The name of the attribute you want to filter against.
          example: first_name
        operator:
          type: string
          description: Determine how to evaluate criteria against the field—`exists` returns results if a person in the audience has the attribute; `eq` returns results if the audience has the attribute and the attribute has the `value` you specify.
          enum:
          - eq
          - exists
        value:
          type: string
          description: The value you want to match for this attribute. You must include a value if you use the `eq` operator.
        inverse:
          type: boolean
          default: false
          description: Set to `true` to match people who *don't* meet the condition.
      example:
        field: unsubscribed
        operator: eq
        value: true
    simpleAudienceFilter:
      x-scalar-ignore: true
      anyOf:
      - title: segment
        description: Filter for people who belong to a segment.
        type: object
        properties:
          segment:
            $ref: '#/components/schemas/segmentAudienceFilter'
      - title: audience
        type: object
        description: filter for people who have an attribute or an attribute value.
        properties:
          attribute:
            $ref: '#/components/schemas/attributeAudienceFilter'
    export_description:
      x-scalar-ignore: true
      type: string
      description: A description of the export.
      example: Customers with segment filters—in Purchased Flowers
    export_failed:
      x-scalar-ignore: true
      type: boolean
      description: If true, the export was unsuccessful.
      example: false
    andAudienceFilter:
      x-scalar-ignore: true
      title: and
      type: object
      properties:
        and:
          type: array
          description: Match *all* conditions to return results.
          items:
            type: object
            properties:
              or:
                type: array
                description: Returns results matching *any* conditions.
                items:
                  $ref: '#/components/schemas/simpleAudienceFilter'
              not:
                description: Returns people who don't match the condition inside it. `not` takes a single object, not an array. That object can be one condition, or an `and` or `or` group when you want to exclude people who match a combination of conditions.
                oneOf:
                - title: and
                  type: object
                  properties:
                    and:
                      type: array
                      description: Match *all* conditions to return results.
                      items:
                        $ref: '#/components/schemas/simpleAudienceFilter'
                - title: or
                  type: object
                  properties:
                    or:
                      type: array
                      description: Match *any* condition to return results.
                      items:
                        $ref: '#/components/schemas/simpleAudienceFilter'
                - title: segment
                  type: object
                  properties:
                    segment:
                      $ref: '#/components/schemas/segmentAudienceFilter'
                - title: attribute
                  type: object
                  properties:
                    attribute:
                      $ref: '#/components/schemas/attributeAudienceFilter'
              segment:
                $ref: '#/components/schemas/segmentAudienceFilter'
              attribute:
                $ref: '#/components/schemas/attributeAudienceFilter'
    orAudienceFilter:
      x-scalar-ignore: true
      title: or
      type: object
      properties:
        or:
          type: array
          description: Match *any* condition to return results.
          items:
            type: object
            properties:
              and:
                type: array
                description: Returns results matching *all* conditions.
                items:
                  $ref: '#/components/schemas/simpleAudienceFilter'
              not:
                description: Returns people who don't match the condition inside it. `not` takes a single object, not an array. That object can be one condition, or an `and` or `or` group when you want to exclude people who match a combination of conditions.
                oneOf:
                - title: and
                  type: object
                  properties:
                    and:
                      type: array
                      description: Match *all* conditions to return results.
                      items:
                        $ref: '#/components/schemas/simpleAudienceFilter'
                - title: or
                  type: object
                  properties:
                    or:
                      type: array
                      description: Match *any* condition to return results.
                      items:
                        $ref: '#/components/schemas/simpleAudienceFilter'
                - title: segment
                  type: object
                  properties:
                    segment:
                      $ref: '#/components/schemas/segmentAudienceFilter'
                - title: attribute
                  type: object
                  properties:
                    attribute:
                      $ref: '#/components/schemas/attributeAudienceFilter'
              segment:
                $ref: '#/components/schemas/segmentAudienceFilter'
              attribute:
                $ref: '#/components/schemas/attributeAudienceFilter'
    drafts:
      x-scalar-ignore: true
      description: If true, your request returns both drafts and active/sent messages.
      type: boolean
    exportSharedProps:
      x-scalar-ignore: true
      description: Contains properties shared by export filters.
      type: object
      properties:
        start:
          $ref: '#/components/schemas/start'
        end:
          $ref: '#/components/schemas/end'
        attributes:
          description: Recipient attributes you want to include as extra columns in your export. You can't include event or trigger properties.
          type: array
          items:
            type: string
        metric:
          $ref: '#/components/schemas/metric'
        drafts:
          $ref: '#/components/schemas/drafts'
        template_id:
          type: integer
          description: Restrict the export to a specific message template (content) within the selected automation, one-time send, or transactional message.
    export_type:
      x-scalar-ignore: true
      type: string
      description: The type of information contained in the export.
      enum:
      - customers
      - deliveries
      example: customers
    created:
      x-scalar-ignore: true
      type: integer
      format: unix timestamp
      description: The date time when the referenced ID was created.
      example: 1552341937
      readOnly: true
  headers:
    Retry-After:
      description: How many seconds you must wait before you send another request. This header is present when you are rate limited by a per-second limit. If you hit a daily quota, this header is not set.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    '429':
      description: Your request is over the 10-per-second limit. `Retry-After` tells you how many seconds you must wait before you send the next request.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/appApiError'
          example:
            errors:
            - detail: rate limited to 10 requests per 1s (reference a1b2c3)
              status: '429'
  parameters:
    export_id:
      name: export_id
      in: path
      required: true
      description: The export_id you want to access.
      schema:
        type: integer
  securitySchemes:
    Tracking-API-Key:
      type: http
      scheme: basic
      description: 'The Track API uses a basic authentication scheme. Your credentials are your **Site ID** and your **API key**, **Base-64 encoded** in the format `site_id:api_key`.


        You can find your Site ID and API key on the [Track API Keys page](https://fly.customer.io/settings/api_credentials).

        '
    Bearer-Auth:
      type: http
      scheme: bearer
      description: 'The App API uses a bearer authentication scheme.


        You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).

        '
    ServiceAccount-Auth:
      x-scalar-ignore: true
      type: http
      scheme: bearer
      bearerFormat: sa_live_
      description: 'Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/whatsapp`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.


        Service-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it''s workspace-scoped, easier to rotate, and has a smaller blast radius.


        Service-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token.
x-tagGroups:
- name: Track API v2
  tags:
  - track_v2
  - Object Schemas
  - Person Schemas
  - Deliveries
- name: Track API
  tags:
  - trackOverview
  - trackJsOrBackend
  - trackLimit
  - trackRegion
  - Track Customers
  - Track Events
  - Forms
  - Track Segments
  - Track v1 Overview
- name: App API
  tags:
  - appOverview
  - appLimit
  - appAuth
  - Activities
  - Automations
  - Broadcasts
  - Collections
  - Customers
  - Data Index
  - ESP Suppression
  - Exports
  - Imports
  - Info
  - Live Notifications
  - Messages
  - Newsletters
  - Opt-outs
  - Reporting Webhooks
  - Segments
  - Sender Identities
  - Snippets


# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/customer-io/openapi/customer-io-exports-api-openapi.yml