Skip to main content
Every call and web session is a session, and there are two ways to read one. The status read is lean and safe to poll while the call is live. The detail read is the full record, and it fills in only after the call ends. Both take the sessionId, the callId from the dispatch response.

​
While the call is live, poll the status

Session status says where the call stands right now: state, the timestamps, failureReason, endedBy, and the variables you passed in. It also names the version that ran: assistantVersion is its number, and assistantAlias is prod or draft when you launched by alias. To hear the call as it happens, use live listen.

​
After the call, read the detail

Session detail is the same record plus everything the call produced: the transcript as timed turns, the toolCalls with arguments and results, the grade from your scorecard with sentiment, a summary in English with a headline, bullets and facts for whoever will not read the transcript, any conversion, any callback the contact asked for with its timeline, and the recording.
None of that exists until the call ends. While a call is live, the detail read does not fail. It returns 200 with the same fields as the status read, an empty transcript, an empty toolCalls, and no grade, conversion, or callback.
Here is why. The transcript and tool calls come from the agent’s session report, uploaded as it shuts down, and land within seconds of hangup. Grading and the summary come last, and the webhooks fire after them. The summary is written for connected calls of stored assistants only, and never for a transient one. How it works has the full sequence. Two rules fall out of this:
  • On call.completed, read the detail immediately. Everything is written by then.
  • If you poll, poll the status. When state is completed or failed, read the detail. An empty transcript on a connected call that ended seconds ago means the report has not landed. Read again.

​
What a finished call looks like

A real outreach call, trimmed to the fields that matter, with the name replaced. gradedAt sits just over a second after endedAt:
endedBy: callee says the farmer hung up. The Call end reasons page covers agent and the rest. grade.score can be null. That means the call was graded but no criterion applied to it. Check for null before you compare the score to a threshold.

​
The recording

Add include_audio_url=true to the detail read for audioUrl. The link is presigned and valid for one hour, so mint it when you need it. On a call that was never recorded, like a failed dial, the link is signed anyway and fails with a 404 or 403 when fetched.

​
Finding a session

List an assistant’s sessions returns status-shaped rows, newest first, filtered by channel, direction, state, and a createdAt range set with from and to. Filters apply after each page is read, so a page can come back short or empty with a nextCursor still present. Keep paging until it is absent. Add include_summary=true and each row carries its call’s summary, so a list can show what happened without a detail read per call. A row with no summary leaves the key out rather than sending null. Records are kept for 90 days.