API reference · Dashboard

List conversations

One page of conversations.

gethttps://api.integrable.cloud/api/bots/{bot_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

bot_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
  21 fields · ConversationRead
  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
  total_cost_usdnumber
  Default: 0
- 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.

Example request

curl

curl "https://api.integrable.cloud/api/bots/$BOT_ID/conversations" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY"

Set INTEGRABLE_API_KEY and the path variables first. The same call from the TypeScript or Python SDK takes the same fields.

Example response

200 OK · application/json

{
  "has_more": false,
  "items": [
    {
      "consent": "unknown",
      "contact_email": "sam@example.com",
      "contact_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
      "contact_name": "string",
      "contact_phone": "+15550100",
      "custom_fields": {},
      "ended_at": "2026-09-03T09:30:00Z",
      "id": "01a0652b-3713-7ea1-a6c9-2e895389ec34",
      "is_lead": false,
      "last_message_at": "2026-09-03T09:30:00Z",
      "message_count": 0,
      "page_url": "https://example.com",
      "rating": 0,
      "resolved": true,
      "sentiment": "string",
      "started_at": "2026-09-03T09:30:00Z",
      "status": "string",
      "summary": "string",
      "title": "string",
      "total_cost_usd": 0,
      "visitor_id": "01a0652b-3713-7ea1-a6c9-2e895389ec34"
    }
  ],
  "next_cursor": "string",
  "page": 0,
  "page_size": 20,
  "total": 0
}

Generated from the schema above — the shape is exact, the values are placeholders.

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-bot limit on top.

More Dashboard endpoints

Something here wrong or missing? Tell us — the documentation and the API are maintained by the same person, so a correction is a fix rather than a ticket.