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

> [!NOTE]
>
> **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Query Parameters

**limit** `number`

The number of conversations to return, from `0` to `1000`. Defaults to `1000`.

**from** `number`

The number of conversations to skip before the first one returned. Use it with `limit` to page through results. Defaults to `0`.

**sort\_by** `string`

Field to sort by. Allowed values: `created_at`, `updated_at`, `last_message_at`, `message_count`. Defaults to `created_at`.

**ascending** `boolean`

Sort in ascending order when `true`. Defaults to `false` (newest first).

**filters** `object[]`

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`, `agent_id`, `agent`
* `operator`: one of `equals`, `not`, `in`, `notIn`, `contains`, `startsWith`, `endsWith`, `gt`, `gte`, `lt`, `lte`, `isEmpty`, `isNotEmpty`, `hasSome`, `hasEvery`, `none`. An operator outside the accepted set fails with `400` and error code `INVALID_PARAMETER`.
* `value`: the filter value. `in` and `notIn` take an array.

To list the conversations a V2 agent ran, filter on `agent_id` with `equals` or `in`. `agent_id` takes `equals`, `not`, `in`, `notIn`, `isEmpty`, and `isNotEmpty`, and its value must be a UUID. The `agent` field also matches conversations created before the agent was recorded on them, and takes `equals` or `in`.

### Response

**data** `array`

A list of conversations matching the query.

**data\[].id** `string`

Unique ID of the conversation.

**data\[].created\_at** `string`

ISO timestamp when the conversation was created.

**data\[].updated\_at** `string`

ISO timestamp when the conversation was last updated.

**data\[].user\_number** `string`

The user-facing phone number in the conversation.

**data\[].agent\_number** `string`

The assistant's phone number in the conversation.

**data\[].variables** `object`

Arbitrary variables associated with the conversation.

**data\[].current\_node\_id** `string`

ID of the current node in the conversational pathway.

**data\[].curr\_pathway\_id** `string|null`

The UUID of the current pathway being used in this conversation.

**data\[].is\_active** `boolean`

Indicates whether the conversation is still active.

**data\[].message\_count** `number`

Number of messages in the conversation.

**data\[].last\_message** `string|null`

The content of the most recent message, if available.

**data\[].last\_message\_at** `string|null`

The timestamp of the most recent message.

**data\[].pathway\_tags** `array|null`

Tags from pathway nodes visited during the conversation.

**data\[].effective\_channel** `string|null`

The resolved delivery channel: `"sms"`, `"rcs"`, or `"whatsapp"`.

**data\[].summary** `string|null`

AI-generated conversation summary, if available.

**data\[].citation\_variables** `object|null`

Extracted citation variable values, if citation schemas were configured.

**data\[].disposition\_tag** `string|null`

The first successful outcome result tag, if outcomes were configured.

**data\[].agent\_id** `string|null`

The V2 agent the conversation ran, or `null` for a pathway or persona conversation. On an agent conversation, `citation_variables` and `disposition_tag` stay empty, and `curr_pathway_id` can be an ID that Bland manages for the agent rather than a pathway you created.

**data\[].agent\_version\_id** `string|null`

The agent version the conversation ran, when Bland can tell which one. `null` otherwise.

**data\[].agent\_dispositions** `array`

The agent's [Dispositions](https://docs.bland.ai/agents/dispositions.md#read-the-results) results for the conversation. Present only when your organization has Dispositions enabled and the page includes an agent conversation. Empty on a conversation that ran no agent.

**errors** `null|array`

`null` on success, or a list of errors on failure.

**extra.pagination.totalItems** `number`

Total number of conversations matching the query.

**extra.pagination.totalPages** `number`

Total number of pages available.

**extra.pagination.currentPage** `number`

The current page of the response.

**extra.pagination.pageSize** `number`

Number of items per page in the current response.

```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,
      "agent_id": null,
      "agent_version_id": null
    }
  ],
  "errors": null,
  "extra": {
    "pagination": {
      "totalItems": 42,
      "totalPages": 5,
      "currentPage": 1,
      "pageSize": 10
    }
  }
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


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