> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Usertick runs surveys on websites, by link, by QR code and by email, and collects every response in one inbox with reports, dashboards and workflows. The REST API lives at https://app.usertick.com/api/public/v1 and uses Bearer API keys or OAuth access tokens; the JavaScript SDK is the @usertick/snippet package on npm.

# Exports

> Export a survey's Results or a dashboard as a CSV or Excel file through the REST API, the same file the Export menu makes, and download it within 24 hours.

The export endpoints produce the same files as the **Export** menu in Usertick: a survey's Results or a dashboard's figures, with samples of recent written answers, as a CSV or Excel file. An export doesn't copy every response, so use [`GET /responses`](https://docs.usertick.com/developers/api/reference/list-responses) to read those.

| Endpoint | Scopes | Does |
| - | - | - |
| [`POST /exports`](https://docs.usertick.com/developers/api/reference/create-export) | `exports:create`, `responses:read` | Starts an export in the background |
| [`GET /exports/{exportId}`](https://docs.usertick.com/developers/api/reference/get-export) | `exports:create` | Returns an export and its file |
| [`GET /exports/{exportId}/download`](https://docs.usertick.com/developers/api/reference/download-export) | `exports:create` | Downloads a finished export's file |

Because a Results file holds samples of written answers, `exports:create` comes with `responses:read`. Like the Export menu, starting an export requires the permission to view surveys.

## Start an export

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://app.usertick.com/api/public/v1/exports \
  -H "Authorization: Bearer $USERTICK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: weekly-checkout-export-2026-11-02" \
  -d '{
    "kind": "results",
    "surveyId": "11111111-1111-4111-8111-111111111111",
    "format": "xlsx",
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-11-01T00:00:00Z",
    "timeZone": "America/New_York"
  }'
```

| Field | Meaning |
| - | - |
| `kind` | `results` for a survey's Results, with `surveyId`, or `dashboard` for a dashboard, with `dashboardId`. |
| `format` | `csv` or `xlsx`. Another format is `400` with `EXP-001-001`. |
| `from`, `to` | The window, `from` included and `to` left out. Without them, the last 30 days. The plan's response history applies, as on the Results page. |
| `timeZone` | The IANA time zone the figures are cut in, `UTC` by default. |
| `filters` | The Results filters: `country`, `device` (`Desktop`, `Tablet` or `Mobile`), `language`, `page`, and for Results also up to 10 `answers`, `timedOut`, `speeders`, `durationMin`, `durationMax` and `variant`. A dashboard takes `country`, `device`, `language` and `page`. |

The call returns `202` with the export and its address in `Location`. A survey the credential can't read returns `404` with `APK-006-005`, and a dashboard it can't read returns `404` with `PUB-015-001`.

## Who the file is read as

Just as the Export menu's file holds what its person reads, an export file holds what the credential reads:

* An **app or an AI assistant** reads as the person who connected it.
* An **API key** reads as the organization, so it exports the dashboards shared with the organization and never a person's private board. The file names the key as its author, such as "Nightly export (API key)".

## Exports and the plan

Each file counts as one of the plan's exports this month, in the same count as the Export menu's files, and once they are used up, `POST /exports` returns `403` with `PLN-001-014`. An export that ends without a file doesn't count. If you send the request again with the same `Idempotency-Key`, it returns the same export and counts once. When Usertick can't start an export right now, the request returns `503` with `EXP-001-006`, and you can try again in a moment.

## Follow an export and download the file

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
  "kind": "results",
  "status": "succeeded",
  "subject": { "type": "survey", "id": "11111111-1111-4111-8111-111111111111", "name": "Onboarding NPS" },
  "format": "xlsx",
  "file": { "name": "onboarding-nps-results.xlsx", "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "bytes": 48213, "expiresAt": "2026-11-06T10:01:00.000Z" },
  "error": null,
  "url": "https://app.usertick.com/api/public/v1/exports/dddddddd-dddd-4ddd-8ddd-dddddddddddd",
  "createdAt": "2026-11-05T10:00:00.000Z",
  "startedAt": "2026-11-05T10:00:02.000Z",
  "finishedAt": "2026-11-05T10:01:00.000Z"
}
```

* `status` is `queued`, `running`, `succeeded` or `failed`. Poll `GET /exports/{exportId}` until it is `succeeded` or `failed`.
* `file` describes the file while Usertick keeps it, with `expiresAt` giving the time it is deleted. It is `null` before the file is made, when the export failed and after the file was deleted.
* `error` says why an export failed: `PUB-013-005` when the survey or the dashboard is gone or the credential can no longer read it, `PUB-004-002` when the file couldn't be made.

`GET /exports/{exportId}/download` redirects with `302` to a link that downloads the file for five minutes, or with `redirect=false` returns `{ "url", "expiresInSeconds" }` instead. While the export has no file, the call returns `409` with `PUB-013-003`. Once the file is deleted, 24 hours after the export finished, it returns `410` with `PUB-013-004`, and you need to start a new export to get the file again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.