This is the object you get back from POST /v1/calls, GET /v1/calls, and GET /v1/calls/{id}. It’s also the body of webhook deliveries.
The transcript is not part of the call object. Fetch it separately via
GET /v1/calls/{id}/transcript (or client.calls.retrieve_transcript /
client.calls.getTranscript in the SDKs).
Fields
Core
| Field | Type | Description |
|---|
id | uuid | Call ID |
agent_id | uuid | null | The agent that handled the call. Null for legacy calls created before agents existed. |
to_number | string | Destination phone number (E.164) |
from_number | string | Caller ID (E.164) |
status | string | Current status (see Statuses) |
direction | string | outbound for calls dispatched via POST /v1/calls; inbound for calls answered by an inbound agent |
persona | string | null | Snapshot of the agent’s persona at the time this call ran |
instructions | string | null | Snapshot of the instructions used for this call (per-call override on outbound, otherwise the agent’s default) |
prompt | string | Rendered system prompt derived from persona + instructions. Read-only call history, not an input field. |
context | object | The context you sent (or null for inbound) |
returns | object | Snapshot of the agent’s returns schema used for this call |
language | string | Language code |
Result
| Field | Type | Description |
|---|
result | object | null | Extracted data matching the returns schema |
result_status | string | pending, completed, or failed |
result_error | string | null | Why extraction failed, if it did |
Timing
| Field | Type | Description |
|---|
created_at | ISO 8601 | When the call was created |
started_at | ISO 8601 | null | When it started ringing |
answered_at | ISO 8601 | null | When someone picked up |
ended_at | ISO 8601 | null | When it ended |
duration_seconds | integer | null | Total duration in seconds |
Billing
| Field | Type | Description |
|---|
billed_duration_seconds | integer | null | Connected time you’re charged for |
billing_amount_milli_cents | integer | null | Charge in milli-cents |
reservation_status | string | reserved, settled, or released |
Webhook (per-call inline)
The fields below are a compatibility layer for the per-call inline
webhook. They summarize delivery of the call.completed event to
webhook_url. For full delivery history, the other seven event types, and
fan-out to multiple endpoints, see Webhooks and
webhook delivery object.
| Field | Type | Description |
|---|
webhook_url | string | null | Effective webhook URL for this call: the per-call override if set, otherwise the agent’s default. Signed with the org’s default secret. |
webhook_status | string | none, pending, delivered, or failed. Reflects the latest inline delivery for this call. |
webhook_error | string | null | Error from the last failed inline delivery. |
Error
| Field | Type | Description |
|---|
error_code | string | null | Telephony provider error code |
error_message | string | null | What went wrong |
hangup_cause | string | null | Telephony-level hangup reason |
| Field | Type | Description |
|---|
metadata | object | Arbitrary metadata on the call |
updated_at | ISO 8601 | Last update time |
Example response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"agent_id": "b5a1c9f2-6d2d-4a7f-9f3a-5a2b1c3d4e5f",
"to_number": "+15551234567",
"from_number": "+15559876543",
"status": "completed",
"direction": "outbound",
"persona": "You are a friendly, professional phone receptionist.",
"instructions": "Confirm the patient's appointment tomorrow at 2pm.",
"prompt": "You are a friendly, professional phone receptionist.\n\nConfirm the patient's appointment tomorrow at 2pm.",
"context": { "patient": "Maria Lopez", "doctor": "Dr. Chen" },
"returns": { "confirmed": "boolean", "reschedule_to": "string" },
"result": {
"confirmed": true,
"reschedule_to": null
},
"result_status": "completed",
"result_error": null,
"language": "en",
"created_at": "2026-04-15T14:30:00Z",
"started_at": "2026-04-15T14:30:01Z",
"answered_at": "2026-04-15T14:30:05Z",
"ended_at": "2026-04-15T14:30:39Z",
"duration_seconds": 38,
"billed_duration_seconds": 34,
"reservation_status": "settled",
"webhook_url": "https://your-server.com/hook",
"webhook_status": "delivered",
"webhook_error": null,
"error_code": null,
"error_message": null,
"hangup_cause": null,
"metadata": {},
"updated_at": "2026-04-15T14:30:45Z"
}
