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

> List your conversations with agents, most recent activity 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 your [sessions](/proposed/objects#session-and-message), most recent activity first. Activity is compared to the second: sessions active within the same second come newest-created first, also compared to the second, and then in a fixed order by session id. So their `updated_at` values, which keep milliseconds, may not be in strict order, but every page continues the same order without repeating or skipping a session. A session is one conversation with an agent. The list holds the sessions you started, in the Wordsmith app or through the API, as the app's own session list does. To read a session someone shared with you, use [Get Session](/api-reference/sessions/get-session) with its id.

Read a session's messages with [List Messages](/api-reference/sessions/list-messages). These endpoints are read-only. To ask a question, in a new session or an existing one, use [Create Question](/api-reference/agents/create-question).

List items leave out `message_count`. [Get Session](/api-reference/sessions/get-session) returns it.

## Authentication

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

## Query parameters

**agent\_id** `string`

Only sessions with this agent. Find agent ids with [List Agents](/api-reference/agents/list-agents).

**query** `string`

Search session titles and message text, up to 200 characters, as the app's session search does. Results come best match first instead of most recent first.

**cursor** `string`

The `cursor` from the previous page. Omit it for the first page.

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

Sessions per page, from `1` to `200`.

## Response

Returns `200` with `{"items": [...], "cursor": "..."}`. Each item is a session. `cursor` is `null` on the last page.

**id** `string`

The session id.

**agent\_id** `string | null`

The agent the session is with, as List Agents names it: `default` for the default agent.

**title** `string | null`

The session's title.

**url** `string`

Opens the session in Wordsmith.

**created\_at** `string`

ISO 8601 UTC.

**updated\_at** `string`

When the last message was added. ISO 8601 UTC.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/sessions?agent_id=3135e518-9205-4887-9ab1-1d56dd38eafb&limit=2" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "items": [
    {
      "id": "6d02931b-eaa1-4c77-b711-66038eb1bb2b",
      "agent_id": "3135e518-9205-4887-9ab1-1d56dd38eafb",
      "title": "Liability cap in the supply agreement",
      "url": "https://app.wordsmith.ai/chat/6d02931b-eaa1-4c77-b711-66038eb1bb2b",
      "created_at": "2026-10-13T14:02:11Z",
      "updated_at": "2026-10-13T14:09:47Z"
    },
    {
      "id": "c5d9f8e2-bc41-4b62-8d82-60dcf103e485",
      "agent_id": "3135e518-9205-4887-9ab1-1d56dd38eafb",
      "title": "Notice periods under the lease",
      "url": "https://app.wordsmith.ai/chat/c5d9f8e2-bc41-4b62-8d82-60dcf103e485",
      "created_at": "2026-10-13T09:30:05Z",
      "updated_at": "2026-10-13T09:31:12Z"
    }
  ],
  "cursor": "eyJvZmZzZXQiOjJ9"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | `limit` is outside `1`–`200`, `cursor` is not one this endpoint returned, or `agent_id` is not an agent id. |
| 404 | `resource_not_found` | No agent with this `agent_id`, or the caller cannot use it. |
| 503 | `temporarily_unavailable` | The session list could not be read just now. It is not empty: retry after a short wait. |


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