# Start an account export

Source: https://workroad.app/docs/api/start-export

`POST https://workroad.app/api/v1/export`

Starts building the account export, or returns the one already being built. It takes a few minutes for a large account; poll `GET /export` until `status` is `ready`. The user also gets an email with a link when it is ready.

- MCP tool: `startExport` on `https://workroad.app/api/mcp`
- Required scopes: account:export
- Test mode: `POST https://workroad.app/api/test/v1/export` checks the request and returns the example response without changing anything.
- Next: poll `getExport` until `status` is `ready`, then download `downloadUrl`.

## Headers

- `Idempotency-Key`: string, optional, 1-255 visible ASCII characters. Makes the POST safe to retry: a retry with the same key and body replays the first response, and the same key with a different body returns 409 `idempotency_conflict`. Kept for 24 hours. Over MCP it is the `idempotencyKey` argument.

## Response

`202` Accepted

- `data`: object, required
  - `id`: string (uuid), required. The export's id.
  - `status`: one of `"pending"`, `"running"`, `"ready"`, `"failed"`, `"expired"`, required. `pending` and `running` while it is built, `ready` while it can be downloaded, `expired` once its download window has passed, `failed` if it could not be built.
  - `createdAt`: string (date-time), required. When the export was requested.
  - `downloadUrl`: string or null, required. When `status` is `ready`: a URL that downloads the ZIP for the next 5 minutes, without credentials. Ask again for a fresh one. Null otherwise.
  - `expiresAt`: string (date-time) or null, required. When `status` is `ready`: when the export stops being available. Null otherwise.
  - `sizeBytes`: integer or null, required. The ZIP's size when `status` is `ready`, else null.

### Example

```json
{
  "data": {
    "id": "4f1c2b3a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "status": "pending",
    "createdAt": "2026-10-28T09:15:00.000Z",
    "downloadUrl": null,
    "expiresAt": null,
    "sizeBytes": null
  }
}
```

## Errors

Every error has the body `{ "error": { "code", "message", "details" } }`.

- `400`: Invalid request body or query
- `401`: Missing, invalid, disabled or expired API key
- `402`: `api_allowance_reached`: this month's API and AI app requests on the free plan are used up. `details` has `limit`, `used`, `resetsAt` and `upgradeUrl`. Nothing ran; WorkRoad Plus has no monthly limit.
- `403`: The API key lacks the required scope
- `404`: No endpoint exists at this path.
- `405`: Method not allowed. Use a method from the Allow header.
- `409`: The Idempotency-Key was reused with a different request body, or a request with the same key is still in progress.
- `429`: Too many exports were started in the last hour, or the engine is busy. Wait for the seconds in `Retry-After`. Rate limit exceeded. Wait for Retry-After before retrying. The rate-limit headers are absent when the key's own limiter rejected the request before the per-endpoint bucket check ran.
- `500`: Internal server error
- `503`: The job engine is unreachable. Send the same request again after `Retry-After` seconds.