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

# Chats

> List and retrieve chats — access customer-visible chat metadata and message counts.

A chat is a conversation thread in your project. The public chats API returns customer-visible chat metadata only. It does not return message bodies or tool/runtime internals.

Only customer-visible chats are returned. Internal chats, evaluation chats, and release-generated chats are excluded from this API.

***

## `GET /v1/chats`

List customer-visible chats for your project.

Returns chats in descending `created_at` order, newest chats first.
Pagination is intentionally based on `created_at` so list traversal stays stable even while a chat continues receiving new messages.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. See [Authentication](/api/authentication).
</ParamField>

<ParamField query="limit" type="integer">
  Number of chats to return. Default `20`, max `100`.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination. Pass the `id` of the last chat from the previous page.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://app.userjourneys.ai/api/v1/chats \
    -H "Authorization: Bearer uj_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://app.userjourneys.ai/api/v1/chats",
    {
      headers: {
        Authorization: "Bearer uj_live_your_key_here",
      },
    }
  );
  const { data, has_more } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.userjourneys.ai/api/v1/chats",
      headers={"Authorization": "Bearer uj_live_your_key_here"},
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "7af6cf75-20ec-49f4-b113-929c01dfbe45",
        "object": "chat",
        "title": "Investigate the spike in onboarding drop-off",
        "source": "web",
        "is_streaming": false,
        "created_at": "2026-04-10T15:18:03.000Z",
        "updated_at": "2026-04-10T15:24:18.000Z"
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>

<Tip>
  This endpoint returns metadata only. To fetch the transcript, use [`GET /v1/chats/:id/messages`](/api/chat-messages).
</Tip>

***

## `GET /v1/chats/:id`

Retrieve a single customer-visible chat with metadata and visible message count.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. See [Authentication](/api/authentication).
</ParamField>

<ParamField path="id" type="string" required>
  Chat ID (UUID).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://app.userjourneys.ai/api/v1/chats/7af6cf75-20ec-49f4-b113-929c01dfbe45 \
    -H "Authorization: Bearer uj_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://app.userjourneys.ai/api/v1/chats/7af6cf75-20ec-49f4-b113-929c01dfbe45",
    {
      headers: {
        Authorization: "Bearer uj_live_your_key_here",
      },
    }
  );
  const chat = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.userjourneys.ai/api/v1/chats/7af6cf75-20ec-49f4-b113-929c01dfbe45",
      headers={"Authorization": "Bearer uj_live_your_key_here"},
  )
  chat = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "7af6cf75-20ec-49f4-b113-929c01dfbe45",
    "object": "chat",
    "title": "Investigate the spike in onboarding drop-off",
    "source": "web",
    "is_streaming": false,
    "message_count": 12,
    "created_at": "2026-04-10T15:18:03.000Z",
    "updated_at": "2026-04-10T15:24:18.000Z"
  }
  ```
</ResponseExample>

This endpoint does not return message bodies. `message_count` counts visible messages only.

Returns `404` if the chat doesn't exist, doesn't belong to your project, or is excluded from the public chats API.

***

## Chat object

<ResponseField name="id" type="string">
  Chat ID (UUID).
</ResponseField>

<ResponseField name="object" type="string">
  `"chat"`
</ResponseField>

<ResponseField name="title" type="string | null">
  Chat title, or `null` if the thread has not been titled.
</ResponseField>

<ResponseField name="source" type="string | null">
  Where the chat originated. Example values include `"web"`, `"analyst"`, and `"mcp"`. Internal-only sources like `"eval"` and `"releases"` are never returned by this API.
</ResponseField>

<ResponseField name="is_streaming" type="boolean | null">
  Whether the chat is currently streaming a response.
</ResponseField>

<ResponseField name="message_count" type="integer">
  Number of visible messages in the chat. Only returned by `GET /v1/chats/:id`. To fetch the actual messages, see [`GET /v1/chats/:id/messages`](/api/chat-messages).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp for when the chat was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp for the most recent update to the chat.
</ResponseField>