> ## 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.

# Run Report

> Compute the cells of a report, all of them or a chosen set of rows and columns.

> [!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).

Starts computing cells in a report and returns a `report_run` [operation](/proposed/objects#operation) straight away. Each cell is the AI's answer to one column's question for one row's document.

A run covers every row and column unless you narrow it with `row_ids` and `column_ids`. By default it skips cells that are already `done`, so a second run only fills new, out-of-date or failed cells. Set `only_empty` to `false` to recompute everything in range. Cells a person approved, rejected or locked in the app are always skipped.

A large grid takes minutes: 200 rows by 10 columns is 2,000 cells. Wait for it with a [callback](/proposed/callbacks) or [Get Operation](/api-reference/operations/get-operation) with `wait`, as described in [Long-running operations](/proposed/long-running-operations). Cells fill in as the run goes, so [List Cells](/api-reference/reports/list-cells) shows partial results before it finishes.

The cells' credit cost is checked against your organisation's per-operation limit before the run starts. When a run already in progress covers the same cells, the new operation follows that run instead of starting a second one. Cancelling such an operation stops only your operation: the run it follows carries on.

[Cancelling](/api-reference/operations/cancel-operation) a run stops it before its next batch of cells. Cells already computing finish, keep their answers and use credits.

## Authentication

Requires an API key, or an OAuth token with `reports:write`. The caller also needs edit access to the report.

## 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, and charging for, a second run.

## Body parameters

**row\_ids** `string[]`

Only compute cells in these rows. Leave it out for every row.

**column\_ids** `string[]`

Only compute cells in these columns. Leave it out for every column.

**only\_empty** `boolean` (default: true)

Skip cells whose `status` is `done`. Set it to `false` to recompute them too. Reviewed cells are always skipped.

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

Seconds to wait for the run to finish before responding, from `0` to `20`. Useful for a run over a handful of cells.

**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_run` and its `resource` is the report. `progress.completed` and `progress.total` count cells.

When the operation succeeds, `result` holds `{ "cells_completed", "cells_total" }`: the cells the run went through, including any that failed, out of the cells in range. A cell that fails does not fail the run. Find failed cells with [List Cells](/api-reference/reports/list-cells) and `status=failed`, then run again: failed cells are retried by default.

If no column in range can be computed, the operation comes back already `succeeded`, with both counts at `0` and no credits used.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/runs" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4e7b1d90-2c5a-4f36-8e0b-a9d3c6f2e581" \
  -d '{
    "column_ids": [
      "0b49a741-bba9-4895-91c0-a5163e60fc22",
      "cae204f5-2bec-47c0-87dc-7399f9aeb7ec"
    ],
    "callback_url": "https://example.com/hooks/wordsmith"
  }'
```

```json Running theme={null}
{
  "id": "25113fa2-7671-4474-b7c6-96794d213c6d",
  "type": "report_run",
  "status": "running",
  "progress": { "stage": "cells", "completed": 0, "total": 428 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T10:10:00Z",
  "updated_at": "2026-10-13T10:10:00Z",
  "completed_at": null
}
```

```json Succeeded theme={null}
{
  "id": "25113fa2-7671-4474-b7c6-96794d213c6d",
  "type": "report_run",
  "status": "succeeded",
  "progress": { "stage": "cells", "completed": 428, "total": 428 },
  "resource": { "type": "report", "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b" },
  "result": { "cells_completed": 428, "cells_total": 428 },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T10:10:00Z",
  "updated_at": "2026-10-13T10:16:48Z",
  "completed_at": "2026-10-13T10:16:48Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | A field has the wrong type, or `row_ids` or `column_ids` is empty. |
| 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. |
| 400 | `process_limit_exceeded` | The cells in range would cost more credits than one operation may use. Nothing runs. |
| 403 | `forbidden` | The caller can read the report but cannot edit it. |
| 404 | `resource_not_found` | No report with this id, the caller cannot read it, or a row or column id is not in it. |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used within 30 days with a different body. |

A run that stops with an error ends as `failed` with `error.code` `run_failed`. A run that makes no progress for an hour ends as `failed` with `worker_lost`. Both are `retryable`.


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