List your chats
/api/v1/chatsList the chats you started in this workspace.
Pages hold up to limit chats and total counts every chat that matches. When has_more is true, pass next_cursor as cursor to read the next page, with the same filters and sort.
search keeps the chats whose title or id contains it, ignoring case. It looks through all your chats in this workspace, not only the page returned.
Required access
Credentials: delegated token, user session, user API key
User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.
Scope: chats:list
Lists the caller's own chats in this workspace, never another member's. Automation accounts have no chats.
A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.
In: header
Query Parameters
Filter by status
Keep agent groups contiguous or return one global list
"list"Value in
- "agent"
- "list"
Order chats by sidebar priority or most recent update
"last_updated"Value in
- "priority"
- "last_updated"
Only pinned chats (true) or only unpinned ones (false); every chat when omitted
Only chats whose title or id contains this text, ignoring case
1 <= value <= 100500 <= value0Opaque cursor returned by the previous page
Header Parameters
Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/chats" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"{ "chats": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "agent_name": "string", "title": "string", "title_source": "auto", "status": "active", "message_count": 0, "messages": [ { "id": 0, "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82", "role": "assistant", "content": "string", "metadata": { "type": "ask_user", "shared_chat": { "token": "string" }, "commentary": [ { "id": "string", "content": "string", "thinking": "string" } ], "activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string", "status": "completed", "duration_ms": 0, "thread": { "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84", "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "request_status": "answered" } } ], "approval": { "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "resource_summary": "string", "effect_details": "string", "attachment_files": [ { "artifact_id": "b7bd6bbb-c7f1-4314-8742-2aeeeece9d12", "file_name": "string", "media_type": "string", "download_only": false, "file_size": 0, "sha256": "string" } ], "risk_level": "string", "always_asks": false, "asks_under_no_approvals": false }, "correlation_id": "string", "preamble": "string", "questions": [ { "question": "string", "suggestions": [ { "label": "string", "recommended": false } ], "allow_other": true } ], "tool_calls_count": 0, "usage": { "model": "string", "tokens_used": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": 0, "duration_seconds": 0 }, "run_error": { "category": "string", "code": "string", "message": "string", "retryable": false }, "limit_detail": { "error": "limit_exceeded", "limit_type": "account.needs_approval", "scope": "agent", "message": "string", "scope_id": "string", "limit": 0, "actual": 0, "retry_after_seconds": 0, "resets_at": "2019-08-24T14:15:22Z" }, "compacted": false, "stopped": false, "stopped_by": { "principal_type": "agent", "name": "string" }, "run_id": 1, "client_ref": "string" }, "run_id": 0, "created_at": "2019-08-24T14:15:22Z", "references": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "knowledge_type": "file", "created_at": "2019-08-24T14:15:22Z", "summary": "string", "caption": "string", "file_name": "string", "file_path": "string", "file_size": 0, "file_type": "string", "height": 0, "width": 0, "duration": 0, "page_count": 0, "thumbnail_url": "string" } ], "attachments": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "chat_session_id": "eab2a04d-304d-443e-9f8d-1a824a2c4f65", "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d", "uploaded_by_user_id": "9fdcaa70-9955-45b2-9821-39697e7541f8", "file_name": "string", "original_file_name": "string", "file_type": "string", "file_size": 0, "checksum": "string", "status": "deleted", "has_extracted_text": false, "thumbnail_sizes": [ "string" ], "metadata": {}, "error": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "artifacts": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "producer_run_id": 0, "root_run_id": 0, "chat_message_id": 0, "visibility": "org_shared", "status": "deleted", "source_kind": "generated", "file_name": "string", "media_type": "string", "download_only": false, "file_size": 0, "sha256": "string", "description": "string", "is_primary": true, "metadata": {}, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] } ], "awaiting_input_kind": "question", "is_running": false, "response_alert_kind": "error", "pinned_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "total": 0, "next_cursor": "string", "has_more": false}