# 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. Processing starts as soon as you create the job. An export is usually ready within minutes. Very large exports finish as you poll the status. A finished file stays available to download for 7 days after it completes. 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 SDK_KEY_ROUTE_FORBIDDEN`, the same as on every other route that is not an SDK endpoint. A member sees the organization's export jobs by default. Free organizations can export even when analytics is frozen at the click limit. A Free export is limited to the last 30 days: a start date before that is refused with `403 LOOKBACK_EXCEEDED` and `details.earliest_allowed`, and no job is created. The same check applies when you download an export, so a Free organization cannot download an export that covers older days, even one made on a paid plan.

## Start an Export

POST /exports: Start a click 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`.

To export only the clicks an AI assistant sent, add `ai_assistant` to the request: one assistant id from the [AI assistant list](https://warplink.app/docs/api/analytics#ai-assistant-traffic), such as `chatgpt`, or `any` for every assistant. It combines with `link_id`. The MCP `export_analytics` tool takes the same `ai_assistant` value.

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

GET /exports/{id}: Get an export job

A job moves through `created`, `cut`, `running`, and then `complete` or `failed`. Poll this endpoint every few seconds until `status` is `complete` or `failed`. A poll of a job that is still `created`, `cut` or `running` may move it forward, so keep polling rather than waiting. `expires_at` is the end of the 7-day download window: it is 7 days after the job completes, and a job that never completes expires 7 days after it was created. 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

GET /exports/{id}/download: Download an export file

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

```bash
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}` every few seconds until `status` is `complete`, then save the file within 7 days:

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