Reports
Run Report
Compute the cells of a report, all of them or a chosen set of rows and columns.
POST
Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive
403 mcp_not_enabled. See the preview overview.report_run 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 or Get Operation with wait, as described in Long-running operations. Cells fill in as the run goes, so 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 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 withreports:write. The caller also needs edit access to the report.
Path parameters
string
required
The report id.
Headers
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
string[]
Only compute cells in these rows. Leave it out for every row.
string[]
Only compute cells in these columns. Leave it out for every column.
boolean
default:"true"
Skip cells whose
status is done. Set it to false to recompute them too. Reviewed cells are always skipped.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.string
An HTTPS URL that receives a signed POST with the operation when it reaches a terminal state. API keys only.
Response
Returns202 with the 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 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.
Errors
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.