Query session list¶

Query the visible sessions in the workspace. It can be filtered by agent, status, purpose or top status, and can be read in sections through paging parameters.

HTTP
GET $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/conversations

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

If you need to filter by agent, first obtain the agent ID.

Set the operation-specific values used in the request:

$AGENT_ID: Optional agent filter ID.

Request¶

Input examples

Shell
curl --get "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/conversations" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "agent_id=$AGENT_ID" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Current workspace ID, must be consistent with `X-Workspace-ID`.

Query parameters

Parameters	Type	Is it required	Description
`agent_id`	string	No	Only return sessions for the specified agent.
`agent_workspace_id`	string	No	ID of the workspace to which the agent belongs. When `agent_id` is specified without this parameter, the current workspace is used; only the current workspace or the system workspace can be specified.
`status`	string	No	Filter by session status.
`purpose`	string	No	Filter by session purpose, can be `chat` or `workflow`.
`pinned`	boolean	No	If it is `true` or `1`, only the pinned conversations will be returned; if it is other values, unpinned conversations will be filtered.
`visibility`	string	No	Accepts only `visible`; only returns visible sessions if not provided.
`parent_conversation_id`	string	No	Filter by parent session ID.
`limit`	integer	No	Single return quantity. `50` when not provided or less than or equal to `0`, up to `200`.
`offset`	integer	No	Returns the offset. `0` when not provided or less than `0`.

Successful response¶

Returns 200 on success. data.items is the session of this page, data.total is the total number of filter results, data.limit and data.offset are the paging values actually used this time.

Response example

JSON
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "conv_01",
        "workspace_id": "ws_01",
        "agent_workspace_id": "ws_01",
        "agent_id": "agent_01",
        "agent_summary": {
          "id": "agent_01",
          "display_name": "销售分析助手",
          "available": true
        },
        "title": "销售分析",
        "status": "active",
        "purpose": "chat",
        "visibility": "visible",
        "pinned": false,
        "created_at": "2026-01-02T15:04:05Z",
        "updated_at": "2026-01-02T15:04:05Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.items`	object[]	Session list on this page.
`data.items[].id`	string	Session ID.
`data.items[].workspace_id`	string	ID of the workspace to which the session belongs.
`data.items[].agent_workspace_id`	string	ID of the workspace to which the agent belongs.
`data.items[].agent_id`	string	Agent ID.
`data.items[].agent_summary`	object	Summary of agent display.
`data.items[].title`	string	Session title; not returned if not set.
`data.items[].status`	string	Session status.
`data.items[].purpose`	string	Session use.
`data.items[].visibility`	string	Session visibility.
`data.items[].pinned`	boolean	Whether to pin it to the top.
`data.items[].head_message_id`	string	Recent message ID; does not return if there is no message.
`data.items[].active_task_id`	string	Current active task ID; does not return if there is no active task.
`data.items[].last_message_at`	string	Last message time; does not return if there is no message.
`data.items[].created_at`	string	Creation and last update times, in RFC 3339 format.
`data.items[].updated_at`	string	Creation and last update times, in RFC 3339 format.
`data.total`	integer	The total number of sessions that meet the filter criteria.
`data.limit`	integer	The upper limit of the actual return quantity used this time.
`data.offset`	integer	The offset actually used this time.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "请求参数无效",
  "details": {
    "cause": "invalid runtime conversation"
  }
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	Invalid agent ID, workspace ID, purpose, visibility, or paging parameters.	Check query parameters; `visibility` can only be `visible`.
`500`	`1`（`INTERNAL`）	The server cannot query the session or generate session display information.	Record the request time and error message and try again.
`503`	`15`（`UNAVAILABLE`）	Session service is temporarily unavailable.	Try again later.

Follow-up operations¶

Use the returned data.items[].id to call Query session details or Query session messages.

Last updated on Sep 15, 2026