Exports

A click export is a background job. You start it with one request, watch its status, and download the finished file when it is complete, so a large export never times out a request. Every export is a snapshot: it holds the clicks that were committed when the job was cut, minus any click deleted before its page was read. A click that arrives later is never in it. Running the same request again creates a new job with a new snapshot, and its file can differ.

Authentication and Permissions

Exports use an API key with the analytics:read or links:read scope. SDK keys are refused with 403 KEY_TYPE_FORBIDDEN, and an SDK key tied to one app is refused the same way it is on every other route. A member sees the organization's export jobs by default. Free organizations can export even when analytics is gated.

Start an Export

The window is clipped once to your plan's data retention, and the response shows the window that was actually exported in window_from and window_to. A window that lies wholly before your plan's retention has nothing to export: the request returns 422 RETENTION_WINDOW_UNAVAILABLE and creates no job. Send your own job_id to make the request safe to repeat: the same id with the same body returns the same job, and the same id with a different body returns 409 EXPORT_JOB_ID_CONFLICT.

An organization has one export in flight at a time. While a job is created, cut or running, starting another returns 409 EXPORT_IN_PROGRESS; start the next one after the first is complete or failed. An organization whose unexpired exports already hold 10 GB of stored files gets 409 EXPORT_QUOTA_EXCEEDED until older exports expire. Neither refusal creates a job.

Get an Export

A job moves through created, cut, running, and then complete or failed. There is no expired status: a job is expired once expires_at has passed. A job that does not exist and a job in another organization both return 404.

Download an Export

Downloads follow one rule, checked in this order:

Condition	Response
expires_at has passed, whatever the status	410 export_expired with the manifest
The job failed	409 export_failed with the manifest
The job is not complete yet	409 export_not_ready
The job is complete and unexpired	200 with the CSV file

Every download of a complete job returns identical bytes. The ETag header and the manifest sha256 are the SHA-256 of the whole file.

Worked Example

curl -X POST https://api.warplink.app/v1/exports \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "since": "2026-03-01T00:00:00Z", "until": "2026-03-02T00:00:00Z" }'

Poll GET /v1/exports/{id} until status is complete, then save the file:

curl -L https://api.warplink.app/v1/exports/JOB_ID/download \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY" \
  -o clicks.csv