Skip to main content
POST
Start an export

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
type
enum<string>
required

events mirrors GET /events; users mirrors GET /users at person grain; attribution is the channel-grain summary from GET /attribution.

Available options:
events,
users,
attribution
params
object
required
format
enum<string>
default:csv

ndjson is one JSON object per line, keyed by the same columns as the CSV.

Available options:
csv,
ndjson

Response

Accepted. The export is queued; poll poll_url for its status. The Location header carries the same path.

id
string<uuid>
required
status
enum<string>
required

Only completed carries a download. expired means expires_at has passed and the file has been deleted.

Available options:
queued,
running,
completed,
failed,
expired
type
enum<string>
required
Available options:
events,
users,
attribution
format
enum<string>
required
Available options:
csv,
ndjson
created_at
string
required
expires_at
string
required

When the file is deleted — seven days after creation. After this the export must be re-run.

params
object

The range and filters this export was created with.

row_count
integer | null

Rows written. Null until the export finishes.

truncated
boolean

True when the export reached the row cap. The file is valid but does not cover the whole requested range; narrow the range or the filters.

error
string | null

Why it failed. Null unless status is failed.

started_at
string | null
completed_at
string | null
download
object | null

Present only on a completed, unexpired job. Generated at poll time, never stored. null alongside download_error means the artifact exists but could not be signed — retry the poll.

download_error
string

Set only when download is null on a completed job.

poll_url
string

Where to poll for this job.

limits
object