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

# Export Report

> Export a report to an Excel, CSV or JSON file.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Exports a report to a new file in your private space and returns a `report_export` [operation](/proposed/objects#operation). The file is the one the report's Download menu produces in the app: one row per document and one column per question.

The export holds the cells as they are when it is built. To export a complete grid, wait for any [run](/api-reference/reports/run-report) to finish first. A report with more than 250,000 cells (rows × columns) is too large to export here; download it from the app.

When the operation succeeds, download the file with [Get File Download](/api-reference/files/get-file-download). See [Long-running operations](/proposed/long-running-operations) for how to wait. An export cannot be cancelled.

## Authentication

Requires an API key, or an OAuth token with `reports:write`. Downloading the file needs `files:read`. The caller needs read access to the report and permission to upload files.

## Path parameters

**report\_id** `string` *required*

The report id.

## Headers

**Idempotency-Key** `string`

A unique string for this request, such as a UUID. A repeat with the same key within 30 days returns the same operation with `200` instead of starting a second export.

## Body parameters

**format** `string` (default: xlsx)

The file format: `xlsx`, `csv` or `json`.

**wait** `integer` (default: 0)

Seconds to wait for the export to finish before responding, from `0` to `20`. Most exports finish within this time.

**callback\_url** `string`

An HTTPS URL that receives a signed POST with the operation when it reaches a terminal state. API keys only.

## Response

Returns `202` with the [operation](/proposed/objects#operation). Its `type` is `report_export` and its `resource` is the report. When it succeeds, `result` holds `{ "file_id" }`: the exported file.

If the export finishes within `wait`, the response is still `202`, and the operation is already `succeeded`.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/exports" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b8d05a3e-61f2-4c97-a0e4-7c3b9f1d2e68" \
  -d '{
    "format": "xlsx",
    "wait": 20
  }'
```

```bash Download the file theme={null}
# Get File Download returns a short-lived signed URL; fetch the file from it without the API key.
url=$(curl -s "https://api.wordsmith.ai/api/v1/files/ae1b497e-7400-4654-a09d-32c24b61b418/download" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" | jq -r .url)
curl -L "$url" -o lease-abstract.xlsx
```

```json Running theme={null}
{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "running",
  "progress": { "stage": "export", "completed": 0, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:00Z",
  "completed_at": null
}
```

```json Succeeded theme={null}
{
  "id": "58fdce17-f67f-49f1-9501-458067b72bce",
  "type": "report_export",
  "status": "succeeded",
  "progress": { "stage": "export", "completed": 1, "total": 1 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": { "file_id": "ae1b497e-7400-4654-a09d-32c24b61b418" },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:20:00Z",
  "updated_at": "2026-10-13T10:20:07Z",
  "completed_at": "2026-10-13T10:20:07Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `format` is not `xlsx`, `csv` or `json`, or a field has the wrong type. |
| 400 | `invalid_wait` | `wait` is outside `0`–`20`. |
| 400 | `invalid_callback_url` | `callback_url` is not a public https URL. |
| 400 | `callback_signing_unavailable` | The API key has no webhook secret to sign the callback with. Create a new API key, or long-poll the operation instead. |
| 403 | `forbidden` | The caller's role does not allow uploading files, so the export has nowhere to go. |
| 404 | `resource_not_found` | No report with this id, or the caller cannot read it. |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used within 30 days with a different body. |

An export of a report that is too large ends as `failed` with `error.code` `report_too_large`. Any other failure ends with `export_failed`, which is `retryable`.


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