Skip to main content
GET
/
v1
/
sms
/
conversations
List Conversations
curl --request GET \
  --url https://api.bland.ai/v1/sms/conversations \
  --header 'authorization: <authorization>'
{
  "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
    }
  }
}
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.
{
  "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