> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Conversations

> Get a paginated list of conversations.

Get a paginated list of conversations.

### Query parameters

<ParamField query="page" type="integer">
  Page number
</ParamField>

<ParamField query="page_size" type="integer">
  Items per page
</ParamField>

<ParamField query="agent_id" type="string,null">
  Filter by agent ID
</ParamField>

### Response

`ConversationListResponse-Input`

<ResponseField name="request_id" type="string,null">
  Request tracking ID
</ResponseField>

<ResponseField name="timestamp" type="string (date-time)">
  Response timestamp
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of items
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="page_size" type="integer">
  Items per page
</ResponseField>

<ResponseField name="has_next" type="boolean">
  Whether there are more pages
</ResponseField>

<ResponseField name="has_prev" type="boolean">
  Whether there are previous pages
</ResponseField>

<ResponseField name="items" type="ConversationSummary[]">
  List of conversations

  <Expandable title="ConversationSummary">
    <ResponseField name="conversation_id" type="string" required>
      Conversation identifier
    </ResponseField>

    <ResponseField name="agent_id" type="string" required>
      Associated agent ID
    </ResponseField>

    <ResponseField name="message_count" type="integer">
      Number of messages
    </ResponseField>

    <ResponseField name="created_at" type="string (date-time)" required>
      Creation timestamp
    </ResponseField>

    <ResponseField name="last_message_at" type="string (date-time),null">
      Last message timestamp
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens used
    </ResponseField>
  </Expandable>
</ResponseField>

### Status codes

| Code  | Meaning                 |
| ----- | ----------------------- |
| `200` | List of conversations   |
| `401` | Authentication required |
| `422` | Validation Error        |
| `429` | Rate limit exceeded     |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'http://localhost:8000/conversations' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-08-31T14:22:05Z",
    "total": 102,
    "page": 1,
    "page_size": 20,
    "has_next": false,
    "has_prev": false,
    "items": [
      {
        "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message_count": 0,
        "created_at": "2026-08-31T14:22:05Z",
        "last_message_at": "2026-08-31T14:22:05Z",
        "total_tokens": 0
      }
    ]
  }
  ```
</ResponseExample>