Exports

About 629 wordsAbout 2 min

Exports let you asynchronously download your event history as JSON or CSV. You submit an export job, the scheduler processes it in the background, and you fetch the result when it's ready.

How it works

POST /v1/exports          →  job.status = "queued"
  ↓ (scheduler picks up within 30s)
job.status = "processing"
  ↓ (query runs, result stored)
job.status = "ready"
  ↓
GET /v1/exports/{id}/download  →  JSON or CSV file

Export job statuses

Status	Description
`queued`	Job accepted, waiting for the scheduler to pick it up
`processing`	Scheduler is running the query
`ready`	Result is available for download
`failed`	Query or encoding failed — see `error_message`

Export filters

All filters are optional. Omitting a filter returns all events.

Field	Type	Description
`direction`	`"inbound"` \| `"outbound"`	Filter by event direction
`status`	string	Filter by event status (e.g. `"dead_letter"`)
`date_from`	ISO 8601	Include events created at or after this timestamp
`date_to`	ISO 8601	Include events created at or before this timestamp

Limit: exports are capped at 10,000 rows per job.

Create export job

POST /v1/exports

Authentication: Bearer

Request body

{
  "format": "json",
  "filters": {
    "direction": "inbound",
    "status": "dead_letter",
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z"
  }
}

Field	Type	Default	Description
`format`	`"json"` \| `"csv"`	`"json"`	Output format
`filters`	object	`{}`	Filter criteria (all optional)

Response `201 Created`

{
  "data": {
    "id": "ex1ex2ex3-e5f6-7890-abcd-ef1234567890",
    "account_id": "a1a2a3a4-...",
    "status": "queued",
    "format": "json",
    "filters": {
      "direction": "inbound",
      "status": "dead_letter",
      "date_from": "2024-01-01T00:00:00Z",
      "date_to": "2024-01-31T23:59:59Z"
    },
    "row_count": null,
    "created_at": "2024-01-15T10:00:00Z",
    "started_at": null,
    "completed_at": null
  }
}

curl example

JOB=$(curl -s -X POST http://localhost:8080/v1/exports \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "filters": { "direction": "inbound" }
  }')

JOB_ID=$(echo $JOB | jq -r '.data.id')
echo "Export job created: $JOB_ID"

List export jobs

GET /v1/exports

Authentication: Bearer

Returns export jobs for the account, newest first.

Query parameters

Parameter	Type	Default	Description
`limit`	int	`25`	Max results (1–200)
`offset`	int	`0`	Pagination offset

Response `200 OK`

{
  "data": [
    {
      "id": "ex1ex2ex3-...",
      "status": "ready",
      "format": "json",
      "row_count": 142,
      "created_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:00:08Z"
    }
  ]
}

Get export job

GET /v1/exports/{id}

Authentication: Bearer

Poll this endpoint to check whether your job is ready.

Path parameters

Parameter	Type	Description
`id`	UUID	The export job ID

Response `200 OK`

{
  "data": {
    "id": "ex1ex2ex3-...",
    "account_id": "a1a2a3a4-...",
    "status": "ready",
    "format": "json",
    "filters": { "direction": "inbound" },
    "row_count": 142,
    "created_at": "2024-01-15T10:00:00Z",
    "started_at": "2024-01-15T10:00:05Z",
    "completed_at": "2024-01-15T10:00:08Z"
  }
}

Errors

Status	Cause
`400`	`{id}` is not a valid UUID
`404`	Job not found or belongs to a different account

Download export result

GET /v1/exports/{id}/download

Authentication: Bearer

Streams the export file. Only available when status = "ready".

Returns the file with the appropriate Content-Type header:

Format	Content-Type
`json`	`application/json`
`csv`	`text/csv`

Path parameters

Parameter	Type	Description
`id`	UUID	The export job ID

Errors

Status	Cause
`400`	Job is not ready yet, or `{id}` is invalid
`404`	Job not found

curl examples

# Download JSON export
curl -s http://localhost:8080/v1/exports/$JOB_ID/download \
  -H "Authorization: Bearer $API_KEY" \
  -o events_export.json

# Download CSV export
curl -s http://localhost:8080/v1/exports/$JOB_ID/download \
  -H "Authorization: Bearer $API_KEY" \
  -o events_export.csv

Full workflow example

# 1. Create export job
JOB_ID=$(curl -s -X POST http://localhost:8080/v1/exports \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv", "filters": {"direction": "inbound"}}' \
  | jq -r '.data.id')

echo "Job ID: $JOB_ID"

# 2. Poll until ready (scheduler runs every 30s)
while true; do
  STATUS=$(curl -s http://localhost:8080/v1/exports/$JOB_ID \
    -H "Authorization: Bearer $API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "ready" ] && break
  [ "$STATUS" = "failed" ] && echo "Export failed" && exit 1
  sleep 5
done

# 3. Download the result
curl -s http://localhost:8080/v1/exports/$JOB_ID/download \
  -H "Authorization: Bearer $API_KEY" \
  -o events.csv

echo "Downloaded $(wc -l < events.csv) rows"