DocsAPI reference

List conversations

One page of conversations.

get/api/agents/{agent_id}/conversations
Authentication
Bearer token
Retries
Safe to repeat
Body
None
Version
2026-09-03

cursor is the mode to use for anything that walks the whole list - exports, infinite scroll, an integration syncing conversations. It is constant-cost at any depth and stable while new conversations arrive; page is neither, and exists because a numbered pager needs it.

search_transcript=true widens q from metadata - visitor, page, contact details, title - to what was actually said, using the full-text index that has been in the schema since the first migration and, until now, was referenced by no query in the codebase.

count=false skips the COUNT(*), which is the half of the request that scans. total comes back as -1 and has_more is the field to read.

outcome, sentiment, intent, min_rating / max_rating, min_lead_score and the date bounds are what make the insight panels lead somewhere. Before them, the dashboard could tell a customer that 22% of their pricing conversations were refused and offer no way to open those twelve conversations - which is a report, not a tool.

Path parameters#

  • agent_idstringrequired

Query parameters#

  • pageinteger

    Default: 1·≥ 1

  • page_sizeinteger

    Default: 20·≥ 1 and ≤ 100

  • statusstring | null
  • has_leadboolean | null
  • qstring | null

    Up to 200 characters

  • search_transcriptboolean

    Default: false

  • sortstring | null

    Up to 64 characters

  • cursorstring | null

    Up to 512 characters

  • countboolean

    Default: true

  • fieldsstring | null

    Up to 500 characters

  • outcomestring | null

    Pattern: ^(resolved|refused|handed_off|abandoned|errored)$

  • sentimentstring | null

    Pattern: ^(positive|neutral|negative)$

  • intentstring | null

    Up to 48 characters

  • min_ratinginteger | null

    ≥ 1 and ≤ 5

  • max_ratinginteger | null

    ≥ 1 and ≤ 5

  • min_lead_scoreinteger | null

    ≥ 0 and ≤ 100

  • unratedboolean | null
  • date_fromstring (date-time) | null
  • date_tostring (date-time) | null

Responses#

  • 200OKapplication/json

    PaginatedResponse_ConversationRead_

    • itemsarray of ConversationReadrequired
      20 fieldsConversationRead
      • idstringrequired
      • last_message_atstring (date-time)required
      • started_atstring (date-time)required
      • statusstringrequired
      • visitor_idstringrequired
      • consentstring

        Default: unknown

      • contact_emailstring | null
      • contact_idstring | null
      • contact_namestring | null
      • contact_phonestring | null
      • custom_fieldsobject
      • ended_atstring (date-time) | null
      • is_leadboolean

        Default: false

      • message_countinteger

        Default: 0

      • page_urlstring | null
      • ratinginteger | null
      • resolvedboolean | null
      • sentimentstring | null
      • summarystring | null
      • titlestring | null
    • pageintegerrequired
    • page_sizeintegerrequired
    • totalintegerrequired
    • has_moreboolean

      Default: false

    • next_cursorstring | null
    5 response headers
    RateLimit-Limit

    Requests permitted in the current window.

    RateLimit-Remaining

    Requests left in the current window. Back off before it reaches 0.

    RateLimit-Reset

    Seconds until the current window resets.

    X-API-Version

    The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.

    X-Request-ID

    Quote this in a support request to identify the call.

  • 422Validation error

    The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Errors#

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

  • validation_error · 422 — The payload was well-formed JSON but failed schema validation.
  • unauthenticated · 401 — The request carried no API key, or one the API could not verify.
  • forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
  • rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.

More Dashboard endpoints#

Something unclear or missing? Tell us and we’ll fix it.