Calls

A call is one voice or video session: a web call, a phone call, a WhatsApp call or a media stream. GET /v1/calls/{session_id} holds what was said, every tool call and its result, the userdata the call ended with, and where the time and money went — the first thing to open when an agent misbehaves. Chats are not calls; read them with GET /v1/chats (text conversations) or under conversations.

List calls

GET /v1/calls returns a page of calls, newest first.

curl -G https://api.talqing.com/v1/calls \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  --data-urlencode "type=SIP_INBOUND" \
  --data-urlencode "outcome=failure" \
  --data-urlencode "limit=50"

const page = await talqing.calls.list({ type: "SIP_INBOUND", outcome: "failure", limit: 50 });
for (const call of page.items) console.log(call.id, call.close_reason_label, call.summary);

from talqing import paginate

for call in paginate(talqing.calls.list, type="SIP_INBOUND", outcome="failure"):
    print(call["id"], call["close_reason_label"], call["summary"])

Parameter	Meaning
`start`, `end`	Window. Default: the last 30 days up to now.
`agent_id`	Calls this agent answered.
`type`	`WEB`, `SIP_INBOUND`, `SIP_OUTBOUND`, `WHATSAPP_INBOUND` or `STREAM`.
`status`	`queued`, `in_progress`, `completed`, `failed` or `canceled`.
`outcome`	`success`, `failure` or `unknown`, from call analysis.
`contact_key`	Every call with one person.
`close_reason`	Exact ending, e.g. `participant_disconnected` (close reasons).
`batch_id`	Calls one call batch placed, retries included.
`metadata`	`key:value`, repeatable, all must match: labels your inbound webhook set.
`limit`, `offset`	Default 200, max 200.

A row carries status, close_reason, close_reason_label, duration_s, cost, contact_key, metadata, recording.state, message_count, total_audio_ms, resumed_from_call_id, the analysis summary and outcome, and plan (non-null only when the call ran something other than the agent’s published version: members, inline, overridden).

Read one call

GET /v1/calls/{session_id} returns the full record.

curl https://api.talqing.com/v1/calls/9c1f6ad2-3b47-4e58-9a2c-7f0d51e8c4b1 \
  -H "Authorization: Bearer $TALQING_API_KEY"

const call = await talqing.calls.get({ session_id: "9c1f6ad2-3b47-4e58-9a2c-7f0d51e8c4b1" });
if (!call.snapshot.ok) console.log(call.snapshot.issues);
console.log(call.session.userdata);

call = talqing.calls.get("9c1f6ad2-3b47-4e58-9a2c-7f0d51e8c4b1")
for issue in call["snapshot"]["issues"]:
    print(issue["kind"], issue["message"])
print(call["session"]["userdata"])

Read it in this order: snapshot.issues, transcript, session.userdata, events.

Top-level fields

Field	Meaning
`session`	The call itself (below).
`snapshot`	Health summary: `ok`, `issues`, latency, tool and pace counters (below).
`transcript`	Every item, in conversation item shape, tool calls included.
`events`	The runtime trace: `{seq, type, payload, created_at}` rows such as `inbound_webhook` (what your inbound webhook answered, at `seq` 0), `agent.ready`, `tool.started`/`tool.ended`, `provider.failed`/`provider.recovered`, `hold.started`/`hold.ended`, `session.error`.
`agent_config`	The resolved config of the agent that answered, overrides applied.
`tools`, `starting_prompt`, `greeting`	The frozen definition this call ran, not the agent’s current draft.
`team`	The roster; `[0]` answered. One entry on an ordinary call.
`agent_plan`	What the request asked for when it differed from the published version; null otherwise.
`vars`	The `{{vars.*}}` values the call started with.
`usage`	Metered usage by kind: `llm`, `stt`, `tts`, `realtime`, `avatar`. LLM rows carry `purpose` (`conversation` or `analysis`) and `priority`.
`cost`	`provider_cost`, `platform_fee`, `total_charge`, `duration_s`, `pricing_snapshot`. Null until billing computes it — see costs.

session

Field	Meaning
`id`, `type`, `status`	Identity and state.
`agent`, `agent_version`	The agent that answered (`{agent_id, name, channel}`) and the published version it ran; null for a draft or inline agent.
`from_e164`, `to_e164`, `phone_number_id`	Phone legs; null on web calls.
`started_at`, `ended_at`, `duration_s`	`duration_s` is null while running and counts only Talqing’s part of a transferred call.
`close_reason`, `close_reason_label`	How it ended, as a code and a sentence.
`error`	Set when the run died on an unhandled error, or was refused with more to say than its close reason (`{type, message}`).
`metadata`	Labels your inbound webhook set; `{}` otherwise.
`contact_key`, `conversation_id`	The person (stable across calls) and this call’s thread.
`userdata`	What the call’s tools wrote — the state it ended with. Analysis is never merged in.
`contact_userdata`	What is stored for this person across all their calls.
`resumed_from_call_id`	The call this one resumed.
`integration_id`, `stream`	The WhatsApp number, or the media-stream connection (`connection_id`, `connection_name`, `dialect`, `codec`, `sample_rate`, `platform_call_id`).
`billing_status`	`pending`, `computed` or `unpriceable`. Only `computed` has a `cost`.
`transfer`	Null unless a transfer was attempted (below).
`recording`, `screen_recording`	`state` and sizes, with signed links — see recordings.
`analysis`	Summary, outcome and fields — see call analysis.
`content_deleted_at`	Set when the call’s content was erased by retention or a delete.

transcript items

`type`	Contents
`message`	`role`, `text`, per-turn `metrics`, a user message’s `origin` (`speech`, `typed`, `keypad`), `attachments` (web calls only), and on a reply the `latency` it took.
`function_call`	`metadata.data`: `name`, `call_id`, `arguments`.
`function_call_output`	`metadata.data`: `output`, `is_error`.
`agent_handoff`	`text` says who took over; `metadata.data.kind` is `handoff`, `task` or `task_return`.
`agent_config_update`	The running agent’s configuration changed mid-call.

Each item carries its own agent_id and agent_version, so on a call with handoffs it says which agent spoke. Items from an inline team member carry null; the preceding agent_handoff names it.

snapshot: latency

snapshot.response_latency is caller-stops-speaking to first agent audio: avg_ms, p95_ms, max_ms, samples. snapshot.response_stages breaks the average into ordered {kind, ms, label} stages:

`kind`	Measures
`stt`	Caller stops talking → final transcript
`endpoint`	Waiting for turn detection to decide the caller is done (turn handling)
`hook`	Your `on_user_turn_completed` hook
`llm_step`	The model deciding to call a tool
`tool`	Waiting for the tool
`llm`	Request → first token
`tts`	First token → first audio byte
`other`	Scheduling, network, buffering

Realtime agents have no stt or tts stage. Per reply, the same list is on transcript[].latency.stages, with latency.kind response (speech → first audio), reply (typed message → first token) or after_filler (a filler line → the tool-driven reply).

snapshot: thresholds and counters

Field	Meaning
`slow_response_threshold_ms`	`3500`. Responses slower than this count as slow.
`slow_tool_threshold_ms`	`8000`. Tools slower than this count as slow.
`slow_tool_calls`, `slow_tool_calls_in_silence`	Slow tools, and the subset with nothing spoken over them (the real defect).
`tool_calls`, `tool_call_failures`, `unfinished_tool_calls`	Unfinished means the run died mid-tool.
`pace`	`longest_agent_turn_ms`, `talk_over_turns`, `hold_ms` (hold music during a bridged transfer; counted in duration, recording and bill).
`connection`	Connection quality split into `agent`, `caller` and `overall`.
`issues`	`{kind, message}` list. `kind` is one of `failed`, `never_ready`, `provider_errors`, `provider_failover`, `tool_failures`, `tools_unfinished`, `slow_tools`, `slow_responses`, `slow_after_filler`, `connection`, `noise_cancellation`, `unpriceable`.

transfer

Field	Meaning
`mode`	`cold` or `warm`.
`transport`	`refer` (SIP REFER, cold transfers on carriers that support it) or `bridge` (every warm transfer).
`destination`	Number dialled.
`outcome`	`connected` or `failed`.
`detail`	The reason the agent was given; null when connected.
`sip_status`	Carrier verdict, e.g. `{"code": 486, "phrase": "Busy Here"}`.
`on_failure`	`continue` or `end_call`.
`at`	When it was attempted.

Stats

GET /v1/calls/stats returns totals over start/end (default last 30 days), optionally by agent_id: total_calls, priced_calls, total_minutes, total_spend and avg_cost_per_call (over priced calls), judged_calls and successful_calls (over calls analysis judged), and the resolved start, end.

Delete a call

DELETE /v1/calls/{session_id} returns 202 and erases the call’s content within seconds: recordings, transcript and tool calls, userdata, summary and extracted fields, and the phone numbers. The call row, status, duration, outcome, timings, cost and usage stay, and content_deleted_at is stamped. A call still in progress is a 409.

Erasing a person’s last remaining call also erases the contact’s stored userdata: the next call from them starts with no memory of them. This cannot be undone.

To delete only the audio, use DELETE /v1/calls/{session_id}/recording. Retention runs the same purge on a schedule — see data retention and privacy.

Debugging agents

Symptom first: which field answers it.

Close reasons

Every close_reason value.

Get started

Build

Guides

List calls

Read one call

Top-level fields

session

transcript items

snapshot: latency

snapshot: thresholds and counters

transfer

Stats

Delete a call

Debugging agents

Close reasons

​List calls

​Read one call

​Top-level fields

​session

​transcript items

​snapshot: latency

​snapshot: thresholds and counters

​transfer

​Stats

​Delete a call

Debugging agents

Close reasons

List calls

Read one call

Top-level fields

session

transcript items

snapshot: latency

snapshot: thresholds and counters

transfer

Stats

Delete a call