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

# List Conversations

> Retrieve a paginated list of SMS conversations for the authenticated user, with filtering, sorting, and metadata.

<Info>
  **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access.
</Info>

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Query Parameters

<ParamField query="page" type="number" required={false}>
  The page number to retrieve. Defaults to `1`.
</ParamField>

<ParamField query="pageSize" type="number" required={false}>
  The number of conversations per page. Defaults to `25`.
</ParamField>

<ParamField query="sortBy" type="string" required={false}>
  Field to sort by. Allowed values: `created_at`, `updated_at`, `user_number`, `agent_number`, `is_active`, `message_count`, `curr_pathway_id`, `curr_pathway_version`, `timed_out_at`. Defaults to `created_at`.
</ParamField>

<ParamField query="sortDir" type="string" required={false}>
  Direction of sorting. Either `asc` or `desc`. Defaults to `desc`.
</ParamField>

<ParamField query="filters" type="object[]" required={false}>
  A JSON-encoded array of filter objects. Each object should contain:

  * `field`: one of `created_at`, `updated_at`, `user_number`, `agent_number`, `is_active`, `message_count`, `variables`, `current_node_id`, `curr_pathway_id`, `curr_pathway_version`, `timed_out_at`
  * `operator`: one of `eq`, `contains`, `startsWith`, `endsWith`, `gt`, `gte`, `lt`, `lte`
  * `value`: the filter value
</ParamField>

### Response

<ResponseField name="data" type="array">
  A list of conversations matching the query.
</ResponseField>

<ResponseField name="data[].id" type="string">
  Unique ID of the conversation.
</ResponseField>

<ResponseField name="data[].created_at" type="string">
  ISO timestamp when the conversation was created.
</ResponseField>

<ResponseField name="data[].updated_at" type="string">
  ISO timestamp when the conversation was last updated.
</ResponseField>

<ResponseField name="data[].user_number" type="string">
  The user-facing phone number in the conversation.
</ResponseField>

<ResponseField name="data[].agent_number" type="string">
  The assistant's phone number in the conversation.
</ResponseField>

<ResponseField name="data[].variables" type="object">
  Arbitrary variables associated with the conversation.
</ResponseField>

<ResponseField name="data[].current_node_id" type="string">
  ID of the current node in the conversational pathway.
</ResponseField>

<ResponseField name="data[].curr_pathway_id" type="string|null">
  The UUID of the current pathway being used in this conversation.
</ResponseField>

<ResponseField name="data[].is_active" type="boolean">
  Indicates whether the conversation is still active.
</ResponseField>

<ResponseField name="data[].message_count" type="number">
  Number of messages in the conversation.
</ResponseField>

<ResponseField name="data[].last_message" type="string|null">
  The content of the most recent message, if available.
</ResponseField>

<ResponseField name="data[].last_message_at" type="string|null">
  The timestamp of the most recent message.
</ResponseField>

<ResponseField name="data[].pathway_tags" type="array|null">
  Tags from pathway nodes visited during the conversation.
</ResponseField>

<ResponseField name="data[].effective_channel" type="string|null">
  The resolved delivery channel: `"sms"`, `"rcs"`, or `"whatsapp"`.
</ResponseField>

<ResponseField name="data[].summary" type="string|null">
  AI-generated conversation summary, if available.
</ResponseField>

<ResponseField name="data[].citation_variables" type="object|null">
  Extracted citation variable values, if citation schemas were configured.
</ResponseField>

<ResponseField name="data[].disposition_tag" type="string|null">
  The first successful outcome result tag, if outcomes were configured.
</ResponseField>

<ResponseField name="errors" type="null|array">
  `null` on success, or a list of errors on failure.
</ResponseField>

<ResponseField name="extra.pagination.totalItems" type="number">
  Total number of conversations matching the query.
</ResponseField>

<ResponseField name="extra.pagination.totalPages" type="number">
  Total number of pages available.
</ResponseField>

<ResponseField name="extra.pagination.currentPage" type="number">
  The current page of the response.
</ResponseField>

<ResponseField name="extra.pagination.pageSize" type="number">
  Number of items per page in the current response.
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "convo_abc123",
        "created_at": "2024-11-20T14:01:00.000Z",
        "updated_at": "2024-11-21T09:12:00.000Z",
        "user_number": "+15550001111",
        "agent_number": "+15552223333",
        "variables": { "campaign_id": "xyz789" },
        "current_node_id": "node_intro",
        "curr_pathway_id": "pathway_abc123",
        "is_active": true,
        "message_count": 5,
        "last_message": "Hi there, how can I help you?",
        "last_message_at": "2024-11-21T09:12:00.000Z",
        "pathway_tags": [{"name": "Greeting", "color": "#4287f5"}],
        "effective_channel": "sms",
        "summary": null,
        "citation_variables": null,
        "disposition_tag": null
      }
    ],
    "errors": null,
    "extra": {
      "pagination": {
        "totalItems": 42,
        "totalPages": 5,
        "currentPage": 1,
        "pageSize": 10
      }
    }
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)