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. Campaign ids contain # and can contain +, so percent-encode them.
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 or callback the grader extracted, 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.
- 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. 