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

# List Cells

> Page through the cells of a report, filtered by row, column or status.

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

Returns a page of [cells](/proposed/objects#report) from a report, row by row in display order. A cell is one column's answer for one row's document. You can call this during a run to read cells as they finish. Match `row_id` to a document with [List Rows](/api-reference/reports/list-rows).

This endpoint allows bigger pages than the others, up to 1,000 cells, because grids are large. To read one row, pass `row_id`. To read one column across every document, pass `column_id`.

## Authentication

Requires an API key, or an OAuth token with `reports:read`.

## Path parameters

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

The report id.

## Query parameters

**row\_id** `string`

Only cells in this row.

**column\_id** `string`

Only cells in this column.

**status** `string`

Only cells with this status: `empty`, `pending`, `computing`, `done` or `failed`.

**cursor** `string`

The `cursor` from the previous page. Leave it out for the first page.

**limit** `integer` (default: 200)

Cells per page, from `1` to `1000`. Keep it, and the filters, the same for every page of a walk.

## Response

Returns `200` with a page of [cells](/proposed/objects#report). `cursor` is `null` on the last page. With `status`, one page reads at most 500 rows, so a page can hold fewer cells than `limit` and still have a `cursor`.

`status` is `empty` for a cell no run has computed, or whose answer went out of date when its column changed. It is `pending` while a run will compute it, including a `done` or `failed` cell a rerun will recompute (its old answer is hidden until then), `computing` while one is, and `done` or `failed` after.

`value` has the column's type: a string for `text`, `date` (ISO 8601) and `single_select`, a number for `number`, a boolean for `boolean`, and a string array for `multi_select`. It is `null` until the cell is `done`, and when the document has no answer. `display_value` is the text the app shows. `citations` lists the passages the answer relies on, as `{ "file_id", "text", "page" }`. `text` is the quoted passage when the citation stored one; most point at a `page` instead, so `text` is often `null`. `reviewed` is `true` for a cell a person approved, rejected or locked in the app; runs leave it alone.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b/cells?row_id=0a0b862f-a721-4cc6-b6f9-db8da95455f7" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "items": [
    {
      "row_id": "0a0b862f-a721-4cc6-b6f9-db8da95455f7",
      "column_id": "6294d0a0-e64f-41ba-96c5-47eb505e7ab0",
      "value": "England and Wales",
      "display_value": "England and Wales",
      "status": "done",
      "citations": [
        {
          "file_id": "5fd5db90-5cd3-46b6-87d9-c828732551ef",
          "text": "This Lease shall be governed by and construed in accordance with the law of England and Wales.",
          "page": 38
        }
      ],
      "reviewed": false,
      "updated_at": "2026-10-13T09:24:11Z"
    },
    {
      "row_id": "0a0b862f-a721-4cc6-b6f9-db8da95455f7",
      "column_id": "a7335c50-fd65-45ec-90d7-b0b0341eb148",
      "value": "2036-03-24",
      "display_value": "2036-03-24",
      "status": "done",
      "citations": [
        {
          "file_id": "5fd5db90-5cd3-46b6-87d9-c828732551ef",
          "text": null,
          "page": 2
        }
      ],
      "reviewed": true,
      "updated_at": "2026-10-13T09:24:13Z"
    },
    {
      "row_id": "0a0b862f-a721-4cc6-b6f9-db8da95455f7",
      "column_id": "56cdb1cf-a2ea-4102-ad7e-dfa91c94c897",
      "value": null,
      "display_value": "",
      "status": "computing",
      "citations": [],
      "reviewed": false,
      "updated_at": "2026-10-13T09:24:20Z"
    }
  ],
  "cursor": null
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `status` is not a known value, or `limit` is not an integer from `1` to `1000`. |
| 400 | `bad_request` | `cursor` is not one this endpoint issued, or `limit` or a filter changed mid-walk. |
| 404 | `resource_not_found` | No report with this id, the caller cannot read it, or `row_id` or `column_id` is not in it. |


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