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

# List Chats

> Retrieve chats for the authenticated user with pagination

Returns a paginated list of chat conversations, sorted by most recent activity. Results are returned 20 per page.

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the authenticate endpoint.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number (1-based). Values less than 1 are treated as 1.
</ParamField>

## Response

<ResponseField name="chats" type="array" required>
  List of chat conversations for the requested page.

  <Expandable title="Chat object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the chat.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Display title for the chat.
    </ResponseField>

    <ResponseField name="preview" type="string">
      Preview of the first message in the chat.
    </ResponseField>

    <ResponseField name="timestamp" type="string" required>
      ISO 8601 timestamp of the most recent activity.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Additional metadata about the chat.

      <Expandable title="Metadata properties">
        <ResponseField name="source_type" type="string">
          Type of datasource used. Either `"database"` or `"project"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of chats across all pages.
</ResponseField>

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

<ResponseField name="page_size" type="integer" required>
  Number of chats per page (currently `20`).
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether additional pages exist beyond the current page.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.trellis.sh/v1/chats?page=1" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.trellis.sh/v1/chats",
      params={"page": 1},
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  data = response.json()
  chats = data["chats"]
  has_more = data["has_more"]
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.trellis.sh/v1/chats?page=1", {
    headers: { Authorization: "Bearer YOUR_TOKEN" },
  });
  const { chats, total, page, page_size, has_more } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "chats": [
      {
        "id": "chat_abc123",
        "title": "Revenue Analysis",
        "preview": "Show me the monthly revenue trends...",
        "timestamp": "2025-01-11T14:30:00Z",
        "metadata": {
          "source_type": "database"
        }
      },
      {
        "id": "chat_def456",
        "title": "Customer Insights",
        "preview": "Which customers have the highest...",
        "timestamp": "2025-01-10T10:15:00Z",
        "metadata": {
          "source_type": "database"
        }
      }
    ],
    "total": 25,
    "page": 1,
    "page_size": 20,
    "has_more": true
  }
  ```
</ResponseExample>