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, and only sessions in the caller’s current workspace are visible — pass workspace_id to list sessions in another workspace the caller belongs to.

Authentication

X-API-KEYstring
API Key authentication via header

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)

aop_asset_idstring or nullOptional
Only include task sessions originating from this AOP asset identifier
workspace_idstring or nullOptional

Workspace to list sessions from. Defaults to the caller’s current workspace; any other workspace the caller is a member of can be requested explicitly.

trigger_typelist of strings or nullOptional

Trigger type(s) to filter by (e.g. ‘schedule’, ‘api’, ‘email’). Repeat the parameter or pass a comma-separated list.

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