List conversations
GET /api/conversations
Returns a paginated list of the conversations of a workspace, optionally filtered by status or text search. Results are ordered by the most recent activity (lastMessageAt). Pagination is cursor-based: pass the nextCursor value from one response as the cursor parameter of the next, with limit setting the page size.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”The workspace whose conversations are listed. Required, except for an API key restricted to a brand or workspace: such a key that names no workspace receives the conversations of every workspace its restriction covers.
Filter by conversation status. Accepted values: ‘open’, ‘in_progress’, ‘awaiting_contact’, ‘resolved’, ‘closed’, ‘abandoned’.
Maximum number of conversations to return per page. Defaults to 50; values above 100 are capped at 100.
Opaque cursor from a previous response’s nextCursor. Omit it to fetch the first page.
Responses
Section titled “ Responses ”A page of conversations, with nextCursor when more results follow. An API key restricted to a brand or workspace receives only the conversations of the workspaces its restriction covers.
A page of conversations. Pass nextCursor as the cursor query parameter to fetch the next page; when nextCursor is absent there are no more results.
object
The conversations on the current page.
A conversation represents a threaded exchange between a customer and your organization on a specific channel. Conversations are created automatically when a new inbound message arrives, or manually via the compose endpoint. Each conversation tracks its lifecycle through status transitions and maintains links to the associated contact and account.
object
Unique identifier for the conversation.
Example
c1a2b3c4-5678-9abc-def0-1234567890abThe tenant this conversation belongs to.
Example
a0b1c2d3-4567-89ab-cdef-0123456789abThe workspace this conversation is assigned to.
Example
w1a2b3c4-5678-9abc-def0-1234567890abThe channel (email, WhatsApp, chat widget, etc.) through which this conversation is conducted.
Example
ch1a2b3c-5678-9abc-def0-1234567890abThe contact (individual person) participating in this conversation. May be null if the contact has not yet been resolved.
Example
ct1a2b3c-5678-9abc-def0-1234567890abThe account (company or organization) the contact belongs to. May be null for B2C conversations or if the account has not yet been resolved.
Example
ac1a2b3c-5678-9abc-def0-1234567890abCurrent lifecycle status of the conversation. Possible values: ‘open’, ‘in_progress’, ‘awaiting_contact’, ‘resolved’, ‘closed’, ‘abandoned’.
Example
openAI-generated summary of the conversation, updated after each turn. Provides a concise overview of the discussion so far.
Example
Customer asked about delivery times for order #4521. Agent confirmed 3-5 business days to Germany.Subject line of the conversation. For email conversations, this is the email subject. For other channels, it may be AI-generated or null.
Example
Re: Delivery time for order #4521A short description of how the conversation was resolved. Set when the conversation is moved to ‘resolved’ status, either by the AI or a human agent.
Example
Delivery timeline confirmed, customer satisfied.Total number of messages in the conversation thread, including both customer and agent messages.
Example
6Timestamp of the most recent message in the conversation. Null if no messages have been exchanged yet.
Example
2026-03-25T11:42:00.000ZTimestamp when the conversation was created.
Example
2026-03-24T08:15:00.000ZTimestamp when the conversation was last updated (status change, new message, etc.).
Example
2026-03-25T11:42:00.000ZOpaque cursor for the next page. Omitted on the last page.
The request names no workspaceId and the API key is not restricted to a brand or workspace (workspaceId is required). Or a contactId or accountId that is not an id, a cursor that is not a nextCursor this endpoint returned, or, from an API key not restricted to a brand or workspace, a workspaceId that is not an id (Invalid filter or cursor).
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]An API key restricted to a brand or workspace named a workspace outside its restriction, or one that is not a workspace of your account (Workspace not found).
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]