List Conversations

GET

/v1/conversations

Send

Authorization

Query

List conversations the caller may see, optionally bounded to one workspace and filtered by insight fields.

Without org_id the listing spans every organisation the caller owns conversations in or administers. Workspace views pass org_id so only that organisation's conversations are returned, after its membership is asserted; the response then says whether the caller sees every conversation of the workspace (all) or only their own (own).

Insight filters reproduce a dashboard drill-down:

• A topic filter follows the topic to its merge survivor and includes every topic merged into that survivor, so a topic id from before a merge still finds its conversations.
• failed=true matches conversations marked failed, from analysis or from how they ended. failed=false matches analysed (text insight available) conversations that are not failed; conversations not analysed yet are excluded, since they are not known to be fine.
• masked_frustration reads exactly one voice engine population, the one the Hidden frustration KPI reports: voice_population when given, else the default population the summary resolves for the same org_id, agent_id, since and until (org_id is then required). Only conversations whose voice result is available at the current transcript revision and has a paired turn are candidates: true lists those with a masked frustration turn, false those without, so the two partition the KPI denominator. The response names the population and whether it is experimental.
• With any insight filter present, since and until are widened to whole UTC days (since from 00:00 UTC of its day, until through the end of its day), the days the dashboard aggregates count, so the rows match the chart.

Call-metric filters (had_tool_errors, tool_name, slow_replies, min_wait_ms) and the projection sort keys need conversations:analytics in the workspace; without it they are ignored and the list sorts by started_at.

Query Parameters

Response Body

curl -X GET "https://example.com/v1/conversations"

{  "items": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",      "run_id": "string",      "source": "string",      "status": "string",      "started_at": "2019-08-24T14:15:22Z",      "ended_at": "2019-08-24T14:15:22Z",      "visitor_id": "1b5d452e-2897-4f21-ac74-1b59f820ba97",      "insight": {        "text_status": "string",        "outcome": "string",        "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",        "topic_name": "string",        "failed": true,        "text_trajectory": "string",        "primary_root_cause": "string",        "masked_frustration": true      },      "metrics": {        "wait_p50_ms": 0,        "wait_max_ms": 0,        "barge_in_count": 0,        "slow_reply_count": 0,        "had_tool_errors": true      }    }  ],  "total": 0,  "conversation_access": "all",  "voice_population": "string",  "voice_experimental": true,  "conversation_analytics": false,  "conversation_export": false}

{  "detail": [    {      "loc": [        "string"      ],      "msg": "string",      "type": "string"    }  ]}