API ReferenceSessions

List sessions

Beta

Retrieve a paginated list of agent sessions (conversations) with optional title search, state filtering, source channel filtering, date range filtering, and sorting. By default, AOP/workflow runs and branched sub-sessions are excluded.

Authentication

X-API-KEYstring
API Key authentication via header
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

querystring or nullOptional

Keyword to search session titles (case-insensitive)

statelist of strings or nullOptional

Execution state(s) to filter by (e.g. ‘running’, ‘completed’). Repeat the parameter or pass a comma-separated list.

source_channellist of strings or nullOptional

Originating channel(s) to filter by (e.g. ‘web’, ‘api’, ‘agent_email’). Repeat the parameter or pass a comma-separated list.

session_typelist of strings or nullOptional

Session kind(s) to include: ‘session’, ‘video_session’, ‘desktop_session’, ‘mobile_session’. Repeat the parameter or pass a comma-separated list.

app_idstring or nullOptional
Only include sessions belonging to this application identifier
include_sub_sessionsbooleanOptionalDefaults to false

Include branched sub-sessions (excluded by default)

include_task_sessionsbooleanOptionalDefaults to false

Include AOP/workflow task runs (excluded by default)

created_afterdatetime or nullOptional
Only include sessions created at or after this ISO 8601 timestamp
created_beforedatetime or nullOptional
Only include sessions created at or before this ISO 8601 timestamp
sort_byenumOptionalDefaults to updated_at
Field to sort by
Allowed values:
sort_directionenumOptionalDefaults to desc
Sort direction
Allowed values:
limitintegerOptional1-500Defaults to 50

Maximum number of sessions to return per page (1-500)

offsetintegerOptional>=0Defaults to 0
Number of sessions to skip for pagination

Response

Successfully retrieved paginated list of sessions
has_moreboolean
Whether there are more sessions available beyond this page
itemslist of objects
Array of session objects for the current page
limitinteger

Maximum number of sessions returned in this response (1-500)

next_offsetinteger or null
Offset value to use for the next page request, null if no more pages
offsetinteger
Number of sessions skipped from the beginning of the result set
totalinteger
Total number of sessions matching the query filters

Errors

422
Unprocessable Entity Error