Appearance
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 fileExport 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/exportsAuthentication: 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/exportsAuthentication: 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}/downloadAuthentication: 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.csvFull 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"