Skip to main content
GET
List chat threads
🔒 Admin only. Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role. Every user’s AI chat threads in the deployment, most recently updated first, for analyzing how people use the agent. Filters combine with AND; a filter given several values matches any of them. Set includeTurns=true to get each thread’s turns in the same response. A turn is one prompt and everything the agent did to answer it: the final answer, the tools it called, and each query it ran with its SQL, status, row count and any thumbs-up/down feedback. Query result rows are never included. A prompt, answer or SQL longer than 20,000 characters, or an error longer than 2,000, is cut and ends in …. A page holds up to 200 threads, or 50 with turns; a larger first is lowered to that. For an incremental export, keep the newest updatedAt you have seen and pass it as updatedAfter next time. Chat history export is in preview: when it is not enabled for the account, 404 is returned.

Authorizations

Authorization
string
header
required

Token authentication. Send Authorization: Bearer <YOUR_TOKEN>.

Path Parameters

deploymentId
integer
required

Query Parameters

createdAfter
string | null

Only threads whose createdAt is at or after this ISO 8601 date or date-time.

Pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
createdBefore
string | null

Only threads whose createdAt is at or before this ISO 8601 date-time. A date alone (2026-10-01) includes that whole day, UTC.

Pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
updatedAfter
string | null

Only threads whose updatedAt is at or after this ISO 8601 date or date-time. A thread is updated by every new turn, so this is the filter for incremental exports.

Pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
updatedBefore
string | null

Only threads whose updatedAt is at or before this ISO 8601 date-time. A date alone (2026-10-01) includes that whole day, UTC.

Pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
userId
integer[] | null

Cube user ids. Repeat the parameter to match any of several values, up to 100.

Maximum array length: 100
userEmail
string[] | null

User emails, matched case-insensitively against Cube users and against the email an embedded user signed in with. Repeat the parameter to match any of several values, up to 100.

Maximum array length: 100
externalUserId
string[] | null

External ids of embedded-analytics users, as your application passed them. Repeat the parameter to match any of several values, up to 100.

Maximum array length: 100
userType
enum<string> | null

internal for Cube users, external for embedded-analytics users. Combines with the user filters above, which match any of their values.

Available options:
internal,
external
source
enum<string>[] | null

Where the thread was started: web (the Cube app or embedded analytics), api (the Chat API), mcp, slack or scheduled (a scheduled task). Repeat the parameter to match any of several values, up to 100.

Maximum array length: 100
Available options:
web,
api,
mcp,
slack,
scheduled
initialContext
enum<string>[] | null

The surface inside the app the thread began on. Repeat the parameter to match any of several values, up to 100.

Maximum array length: 100
Available options:
chat,
workbook,
model,
dashboard,
external,
mcp,
ai-widget,
onboarding,
explore,
connection_setup,
slack_dm,
published-dashboard,
sheets
agentId
integer[] | null

Agent ids; -1 selects the Auto agent. Repeat the parameter to match any of several values, up to 100.

Maximum array length: 100
search
string | null

Case-insensitive match on the thread title or its chat id.

sortBy
enum<string> | null

Defaults to updatedAt.

Available options:
createdAt,
updatedAt
sortOrder
enum<string> | null

Defaults to desc.

Available options:
asc,
desc
includeTurns
boolean | null

Return every thread with its turns. Pages then default to 20 threads and hold at most 50.

after
string
first
integer
Required range: x >= 1

Response

200 - application/json
items
object[]
required
pageInfo
object
required