Skip to main content
GET
List conversations

Authorizations

Authorization
string
header
required

The id_token from POST /auth/v1/signin, sent as Authorization: Bearer <id_token>. Not the access_token — that one does not carry the identity Cloud Chat authorizes on.

Headers

cloudchat-instance
integer
required

Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.

Example:

1

Path Parameters

accountId
integer
required

Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.

Example:

1

Query Parameters

status
enum<string>

Keep only conversations in this status.

Available options:
open,
resolved,
pending,
snoozed,
proactive
assignee_id
integer

Keep only conversations assigned to this agent, by the agent id.

Example:

7

inbox_id
integer

Keep only conversations of this inbox. An inbox your token cannot see yields an empty page, not an error.

Example:

3

team_id
integer

Keep only conversations assigned to this team.

Example:

2

label
string

Keep only conversations carrying this label, matched exactly.

Example:

"vip"

created_after
string<date-time>

Keep only conversations created at or after this instant. ISO 8601; a date without a time reads as midnight UTC.

Example:

"2026-08-01T00:00:00Z"

created_before
string<date-time>

Keep only conversations created strictly before this instant. Pair with created_after for a half-open range that never double-counts across windows.

Example:

"2026-08-01T00:00:00Z"

updated_after
string<date-time>

Keep only conversations whose last change was at or after this instant. This is the field to poll when you mirror conversations somewhere else.

Example:

"2026-08-01T00:00:00Z"

updated_before
string<date-time>

Keep only conversations whose last change was strictly before this instant.

Example:

"2026-08-01T00:00:00Z"

page
integer
default:1

1-based page number. Anything below 1 — including a non-numeric value — is read as 1.

Required range: x >= 1
Example:

1

per_page
integer
default:25

Results per page. Clamped, never rejected: above 100 you get 100, below 1 you get the default 25.

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

25

Response

A page of conversations. data is empty when nothing matches — an empty page is not a 404.

data
object[]
required

The conversations on this page.

meta
object
required

Where you are in the result set. There is no total count — walk forward while has_next is true.