# List conversations

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

### Query Parameters

- limit - Number of conversations to return (1-100, default 10)
- cursor - Cursor from previous response for pagination

### 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)
- participants - Array of participants
- source - Information about the first message
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example

json
{
  "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.

Endpoint: GET /v2/conversations
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Query parameters:

  - `limit` (integer)
    A limit on the number of objects to be returned, between 1 and 100.
    Example: 10

  - `cursor` (string)
    An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.
    Example: "eyJpZCI6IjEyMzQ1In0="

## Response 200 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "list"

  - `data` (array, required)
    Array of conversations

  - `data.id` (string, required)
    Unique conversation identifier
    Example: "12345"

  - `data.title` (string)
    Conversation title
    Example: "Question about pricing"

  - `data.state` (string, required)
    Current state of the conversation
    Enum: "open", "closed", "snoozed"

  - `data.isBlocked` (boolean, required)
    Whether the user is blocked

  - `data.priority` (boolean, required)
    Whether this conversation is marked as priority

  - `data.prioritySetAt` (string,null, required)
    ISO timestamp when priority was set
    Example: "2025-01-15T10:30:00.000Z"

  - `data.adminAssigneeId` (string,null, required)
    ID of the assigned admin
    Example: "507f1f77bcf86cd799439011"

  - `data.teamAssigneeId` (string,null, required)
    ID of the assigned team
    Example: "507f1f77bcf86cd799439012"

  - `data.userPreferredLanguage` (string, required)
    User's preferred language
    Example: "en"

  - `data.source` (object)

  - `data.source.channel` (string, required)
    Channel through which the conversation was initiated
    Enum: "unknown", "desktop", "android", "ios", "email"

  - `data.source.deliveredAs` (string)
    How the conversation was initiated
    Enum: "customer_initiated", "admin_initiated"

  - `data.source.subject` (string)
    Subject line for email conversations
    Example: "Question about pricing"

  - `data.source.bodyHtml` (string, required)
    Body of the initial message as HTML with signed image URLs
    Example: "<p>Hi, I have a question about your enterprise plan...</p>"

  - `data.source.bodyMarkdown` (string, required)
    Body of the initial message as markdown
    Example: "Hi, I have a question about your enterprise plan..."

  - `data.source.author` (object)

  - `data.source.author.type` (string, required)
    Type of participant
    Enum: "customer", "lead", "admin", "bot", "guest", "integration"

  - `data.source.author.id` (string, required)
    Participant ID
    Example: "676f0f6765bdaa7d7d760f88"

  - `data.source.url` (string)
    URL where the conversation was initiated
    Example: "https://example.com/pricing"

  - `data.participants` (array, required)
    Participants in this conversation

  - `data.botConversationState` (string)
    State of AI agent handling for this conversation
    Enum: "active", "handed_off_to_human", "resolved"

  - `data.botConversationStateLastUpdatedAt` (string,null, required)
    ISO timestamp when bot state last changed
    Example: "2025-01-15T10:30:00.000Z"

  - `data.disableCustomerReply` (boolean)
    Whether customer replies are disabled

  - `data.awaitingCustomerReply` (boolean)
    Whether we are awaiting a customer reply
    Example: true

  - `data.lastActivityAt` (string,null, required)
    ISO timestamp of last activity
    Example: "2025-01-15T12:30:00.000Z"

  - `data.waitingSince` (string,null, required)
    ISO timestamp when conversation started waiting
    Example: "2025-01-15T10:30:00.000Z"

  - `data.snoozedUntil` (string,null, required)
    ISO timestamp until which conversation is snoozed
    Example: "2025-01-16T09:00:00.000Z"

  - `data.createdAt` (string, required)
    ISO timestamp when conversation was created
    Example: "2025-01-15T10:30:00.000Z"

  - `data.updatedAt` (string, required)
    ISO timestamp when conversation was last updated
    Example: "2025-01-15T12:30:00.000Z"

  - `data.readReceipts` (array)
    Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access.

  - `data.readReceipts.id` (string, required)
    The internal ID of the user
    Example: "507f1f77bcf86cd799439011"

  - `data.readReceipts.userType` (string, required)
    Type of user who has read the conversation
    Enum: "admin", "customer", "lead"

  - `data.readReceipts.lastReadPartId` (string, required)
    The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility.
    Example: "8"

  - `data.conversationParts` (array)
    Array of conversation parts (messages). Only included when fetching a single conversation by ID.

  - `nextCursor` (string,null, required)
    Cursor for fetching the next page
    Example: "eyJpZCI6IjEyMzQ1In0="

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_cursor"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400