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

**page** `number`

The page number to retrieve. Defaults to `1`.

**pageSize** `number`

The number of conversations per page. Defaults to `25`.

**sortBy** `string`

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

**sortDir** `string`

Direction of sorting. Either `asc` or `desc`. Defaults to `desc`.

**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`
* `operator`: one of `eq`, `contains`, `startsWith`, `endsWith`, `gt`, `gte`, `lt`, `lte`
* `value`: the filter value

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

**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
    }
  ],
  "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.