Skip to main content
Conversations

List conversations

Returns a list of conversations in your organization using cursor-based pagination.

GET
/v2/conversations

Query Parameters

  • limit - Number of conversations to return (1-100, default 10)
  • cursor - Cursor from previous response for pagination
  • tagIds - Optional tag filter as a comma-separated list of tag IDs. Matches conversations that contain all of the provided tags.

Response Format

Returns a list object with:

  • object - Always "list"
  • data - Array of conversation objects
  • nextCursor - Cursor for the next page, or null if no more results

Conversation Object

Each conversation includes:

  • id - Unique conversation identifier (short ID)
  • title - Conversation title
  • state - Current state ("open", "closed", or "snoozed")
  • priority - Whether the conversation is marked as priority
  • adminAssigneeId - ID of assigned admin (if any)
  • teamAssigneeId - ID of assigned team (if any)
  • tags - Current tags applied anywhere in the conversation
  • participants - Array of participants
  • source - Information about the first message
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

Example

{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": "12345",
      "title": "Question about pricing",
      "state": "open",
      "priority": false,
      "adminAssigneeId": null,
      "participants": [
        { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
      ],
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjEyMzQ1In0="
}

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Query Parameters

limitintegerquerydefault:10

A limit on the number of objects to be returned, between 1 and 100.

Required range: 1 <= x <= 100
Example: 10
cursorstringquery

An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.

Maximum string length: 512
Example: eyJpZCI6IjEyMzQ1In0=
tagIdsstring | string[]query

Filter conversations by one or more tag IDs using a comma-separated list. Conversations must contain all provided tags.

Example: 67ec1234abcd5678ef901234,67ec5678abcd1234ef905678
includestring | string[]query

Comma-separated optional expansions. Use customAttributeDefinitions to return customAttributeValues with names and types alongside ID-keyed customAttributes.

Example: customAttributeDefinitions

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Response

application/json

Success

dataobject[]required

Array of conversations

nextCursorstring | nullrequired

Cursor for fetching the next page

Example: eyJpZCI6IjEyMzQ1In0=
objectenum<string>required

Object type identifier

Available options: list
Example: list

Still need help? Ask the team