Agent conversations
Return the agent conversations accessible to the API key in its project, ordered by last-updated time from newest to oldest. A conversation is accessible when it belongs to the key's creator; conversations belonging to other users are not accessible regardless of the creator's project role. Subagent conversations are excluded from the list but can still be read directly by id. Supplying a query matches conversation titles, user-authored text, assistant response text, tool names, and tool statuses. Results are cursor-paginated: pass the returned next_cursor back unchanged, with the same query and page_size, for the following page. Returns an empty list when nothing matches.
Authorization
ApiKeyAuth External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.
In: header
Query Parameters
Regular expression matched case-insensitively against conversation titles, user text, assistant text, tool names, and tool statuses.
Number of conversations per page.
1 <= value <= 10020Opaque cursor from a previous response's next_cursor.
Response Body
application/json
application/json
curl -X GET "https://example.com/v2/external-api/agent_conversations"{ "items": [ { "object": "agent_conversation", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "origin": "user", "title": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "automation": { "object": "agent_conversation_automation_run", "automation_id": "64fb5f73-6415-4f56-8e9e-ca06539f09ac", "automation_name": "string", "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec", "run_status": "scheduled", "run_started_at": "2019-08-24T14:15:22Z", "run_completed_at": "2019-08-24T14:15:22Z" } } ], "next_cursor": "string"}Return a conversation's user-visible content committed at the time of the request, in chronological order, together with whether the conversation currently has an active turn. Hidden reasoning, system-only content, credentials, and implementation metadata are always excluded; tool calls, inputs, and outputs appear only when include_tool_activity is true. When the content exceeds the response limit, the most recent portion is returned along with a continuation reference — pass it as before_event_id to read the immediately preceding portion. A conversation that originated from an automation also reports its automation and run metadata.
Authorization
ApiKeyAuth External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.
In: header
Path Parameters
uuidQuery Parameters
Include tool calls, inputs, and outputs in the returned content.
falseContinuation reference from a previous read; returns the portion immediately preceding it.
Response Body
application/json
application/json
curl -X GET "https://example.com/v2/external-api/agent_conversations/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "data": { "object": "agent_conversation", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "origin": "user", "title": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "automation": { "object": "agent_conversation_automation_run", "automation_id": "64fb5f73-6415-4f56-8e9e-ca06539f09ac", "automation_name": "string", "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec", "run_status": "scheduled", "run_started_at": "2019-08-24T14:15:22Z", "run_completed_at": "2019-08-24T14:15:22Z" }, "active_turn": { "object": "agent_conversation_active_turn", "is_active": true, "started_at": "2019-08-24T14:15:22Z" }, "content": [ { "object": "agent_conversation_message", "id": "string", "role": "user", "text": "string", "thinking_summary": "string", "is_final": true, "created_at": "2019-08-24T14:15:22Z" } ], "continuation": { "object": "agent_conversation_continuation", "before_event_id": "string" } }}