Skip to main content
GET
List Conversations
Enterprise Feature - SMS is only available on Enterprise plans. Contact your Bland representative for access.

Headers

string
required
Your API key for authentication.

Query Parameters

number
The number of conversations to return, from 0 to 1000. Defaults to 1000.
number
The number of conversations to skip before the first one returned. Use it with limit to page through results. Defaults to 0.
string
Field to sort by. Allowed values: created_at, updated_at, last_message_at, message_count. Defaults to created_at.
boolean
Sort in ascending order when true. Defaults to false (newest first).
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

array
A list of conversations matching the query.
string
Unique ID of the conversation.
string
ISO timestamp when the conversation was created.
string
ISO timestamp when the conversation was last updated.
string
The user-facing phone number in the conversation.
string
The assistant’s phone number in the conversation.
object
Arbitrary variables associated with the conversation.
string
ID of the current node in the conversational pathway.
string|null
The UUID of the current pathway being used in this conversation.
boolean
Indicates whether the conversation is still active.
number
Number of messages in the conversation.
string|null
The content of the most recent message, if available.
string|null
The timestamp of the most recent message.
array|null
Tags from pathway nodes visited during the conversation.
string|null
The resolved delivery channel: "sms", "rcs", or "whatsapp".
string|null
AI-generated conversation summary, if available.
object|null
Extracted citation variable values, if citation schemas were configured.
string|null
The first successful outcome result tag, if outcomes were configured.
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.
string|null
The agent version the conversation ran, when Bland can tell which one. null otherwise.
array
The agent’s Dispositions 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.
null|array
null on success, or a list of errors on failure.
number
Total number of conversations matching the query.
number
Total number of pages available.
number
The current page of the response.
number
Number of items per page in the current response.

Docs for agents: llms.txt