Exports

Exports run asynchronously. Create an export, poll its status until it is ready, then download the generated CSV. Files are subject to an expiry and can only be downloaded by the organization that created them.

---

Create CSV export

POST /v1/exports

Requires read_only scope.

Request body

Field	Type	Required	Description
resource	string	Yes	What to export: contacts, emails, campaigns, or segments.
filters	object	No	Filter map. Recognized keys depend on the resource (e.g. audience_id, status); unknown keys are ignored.

{
  "resource": "contacts",
  "filters": {
    "audience_id": "aud_abc123"
  }
}

Response

{
  "id": "exp_abc123",
  "status": "pending"
}

---

List exports

GET /v1/exports

Requires read_only scope.

Query parameters

Parameter	Type	Default	Description
limit	number	50	Results per page (1-100).
cursor	string		Pagination cursor (export ID).

Response

{
  "data": [
    {
      "id": "exp_abc123",
      "resource": "contacts",
      "status": "ready",
      "filters": {
        "audience_id": "aud_abc123"
      },
      "row_count": 4200,
      "file_url": "/v1/exports/exp_abc123/download",
      "error_message": null,
      "created_at": "2025-03-12T09:00:00Z",
      "completed_at": "2025-03-12T09:00:42Z",
      "expires_at": "2025-03-19T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

---

Get export status

GET /v1/exports/:id

Requires read_only scope. Poll this until status is ready.

Response

{
  "id": "exp_abc123",
  "resource": "contacts",
  "status": "ready",
  "filters": {
    "audience_id": "aud_abc123"
  },
  "row_count": 4200,
  "file_url": "/v1/exports/exp_abc123/download",
  "error_message": null,
  "created_at": "2025-03-12T09:00:00Z",
  "completed_at": "2025-03-12T09:00:42Z",
  "expires_at": "2025-03-19T09:00:00Z"
}

Status values: pending, processing, ready, failed. When failed, error_message explains why.

---

Download export CSV

GET /v1/exports/:id/download

Requires read_only scope. Streams the CSV file for a ready export.

Response

Returns the file as CSV, not JSON, with headers:

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="contacts-exp_abc123.csv"

id,email,first_name,last_name,created_at
con_abc123,ada@acme.com,Ada,Lovelace,2025-03-10T14:22:00Z

Returns 409 not_ready if the export is still running, 410 expired if the file's expires_at has passed, and 404 not_found if the export does not belong to your organization.