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

> List the reports you can read, most recently updated first.

> [!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 the [reports](/proposed/objects#report) you can read, most recently updated first. A report is a grid with one row per document and one AI-answered column per question.

Filter by `repository_id` to find the reports whose rows follow one repository. Reports on the legacy report engine are not listed, and cannot be read through the API.

## Authentication

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

## Query parameters

**repository\_id** `string`

Only reports whose rows follow this repository.

**query** `string`

Only reports whose name contains this text. The match ignores case.

**cursor** `string`

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

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

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

## Response

Returns `200` with a page of [reports](/proposed/objects#report). `cursor` is `null` on the last page. Read one with [Get Report](/api-reference/reports/get-report) to see its columns.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/reports?repository_id=b23066a1-44cb-4b31-8b44-c723dc507d9b" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "items": [
    {
      "id": "f544ddfc-24d5-4947-939c-ba2d1bcba35b",
      "name": "Lease abstract: retail estate",
      "description": "Key terms for every signed retail lease.",
      "repository_id": "b23066a1-44cb-4b31-8b44-c723dc507d9b",
      "row_count": 214,
      "column_count": 3,
      "status": "running",
      "url": "https://app.wordsmith.ai/reports/f544ddfc-24d5-4947-939c-ba2d1bcba35b",
      "created_at": "2026-10-13T09:20:00Z",
      "updated_at": "2026-10-13T09:31:47Z"
    },
    {
      "id": "4d845617-3fad-483d-8eac-eba886e6e31f",
      "name": "Rent review dates",
      "description": null,
      "repository_id": "b23066a1-44cb-4b31-8b44-c723dc507d9b",
      "row_count": 214,
      "column_count": 2,
      "status": "idle",
      "url": "https://app.wordsmith.ai/reports/4d845617-3fad-483d-8eac-eba886e6e31f",
      "created_at": "2026-10-13T08:40:12Z",
      "updated_at": "2026-10-13T08:58:09Z"
    }
  ],
  "cursor": null
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | `cursor` is not one this endpoint issued, or `limit` or a filter changed mid-walk. |
| 400 | `invalid_request_body` | `limit` is not an integer from `1` to `200`. |


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