The call object

Every call endpoint (create-phone-call, create-web-call, get-call, list-calls, stop-call, rerun-call-analysis) and every call webhook returns the same call object. Its shape is defined by CallResponse in packages/shared and matches Retell's field names, so code written against Retell reads it unchanged.

This page explains each field. For the list endpoint and its filters see List calls. For the reasons a call ends see Disconnection reasons.

Lifecycle#

A call moves through these states in call_status:

ended, not_connected and error are terminal. A call becomes not_connected only when it never started and its disconnection reason is one of: dial_busy, dial_failed, dial_no_answer, invalid_destination, registered_call_timeout, error_user_not_joined, no_valid_payment, credit_exhausted, marked_as_spam, telephony_provider_permission_denied, telephony_provider_unavailable, sip_routing_error, concurrency_limit_reached, no_concurrency_fallback, user_declined.

When a call ends, Tried:

1. Sets end_timestamp, duration_ms, disconnection_reason and call_cost.
2. Sends the call_ended webhook.
3. Runs post-call analysis and stores call_analysis.
4. Sends the call_analyzed webhook (always after call_ended).
5. Applies the agent's data storage setting.

Example#

{
  "call_id": "call_7e2f4c1a9b8d0e3f5a6b7c8d",
  "call_type": "phone_call",
  "agent_id": "agent_3f9c0a1b2c3d4e5f6a7b8c9d",
  "agent_version": 4,
  "agent_name": "Receptionist",
  "call_status": "ended",
  "direction": "inbound",
  "from_number": "+61412345678",
  "to_number": "+61291234567",
  "metadata": { "source": "google_ads" },
  "retell_llm_dynamic_variables": { "business_name": "Harbour Dental" },
  "collected_dynamic_variables": { "appointment_time": "Tue 21 Oct, 4pm" },
  "start_timestamp": 1760850000000,
  "end_timestamp": 1760850094000,
  "duration_ms": 94000,
  "transcript": "Agent: Hi, thanks for calling Harbour Dental...\nUser: I'd like to book a check-up.",
  "transcript_object": [
    { "role": "agent", "content": "Hi, thanks for calling Harbour Dental...", "words": [] },
    { "role": "user", "content": "I'd like to book a check-up.", "words": [{ "word": "I'd", "start": 3.1, "end": 3.3 }] }
  ],
  "transcript_with_tool_calls": [],
  "recording_url": "https://...",
  "recording_multi_channel_url": null,
  "public_log_url": "https://api.tried.com.au/public/calls/call_7e2f.../log?exp=...&sig=...",
  "knowledge_base_retrieved_contents_url": "https://api.tried.com.au/public/calls/call_7e2f.../kb-retrievals?exp=...&sig=...",
  "disconnection_reason": "agent_hangup",
  "call_analysis": {
    "call_summary": "The caller booked a check-up for Tuesday at 4pm.",
    "in_voicemail": false,
    "user_sentiment": "Positive",
    "call_successful": true,
    "custom_analysis_data": { "appointment_booked": true }
  },
  "latency": {
    "e2e": { "p50": 910, "p90": 1240, "p95": 1300, "p99": 1350, "max": 1360, "min": 780, "num": 9, "values": [910, 780] }
  },
  "call_cost": {
    "product_costs": [
      { "product": "voice_infra", "unit_price": 0.08, "cost": 0.125333 },
      { "product": "gpt-5.6-terra", "unit_price": 0.1, "cost": 0.156667 },
      { "product": "voice_standard", "unit_price": 0.06, "cost": 0.094 }
    ],
    "total_duration_seconds": 94,
    "combined_cost": 0.376
  },
  "llm_token_usage": { "values": [1210, 1388, 1502], "average": 1367, "num_requests": 3 },
  "batch_call_id": null,
  "transfer_destination": null,
  "contact_id": "contact_1a2b3c4d5e6f7a8b9c0d1e2f"
}

Unit prices come from PRICE_PER_MIN in packages/shared/src/pricing.ts (for example voice_infra 0.08 AUD per minute).

Identity and routing#

Data you pass in#

Timing#

Transcript#

transcript_with_tool_calls item roles:

ts is a millisecond offset from the call start or an absolute epoch ms value.

Recordings and logs#

Signed links for the log and retrievals last 7 days. If the agent enables signed recording URLs, recording links also expire, after signed_url_expiration_ms.

Outcome#

call_analysis fields:

See Post-call analysis and Use analysis results.

Latency#

latency is an object with one entry per stage that produced samples. Each entry has p50, p90, p95, p99, max, min, num (sample count) and values (every sample in ms, one per turn).

Cost and usage#

call_cost:

Products include voice_infra, the LLM model (for example gpt-5.6-terra), the voice (voice_premium or voice_standard), knowledge_base when the agent uses one, and concurrency_burst for burst calls. There is no telephony line: numbers are your own, and your carrier bills the phone line.

llm_token_usage is { values, average, num_requests }: total tokens per LLM request, their average and the request count. It is null when no LLM request was recorded.

Web call fields#

create-web-call responses also carry access_token, livekit_url, expires_at (token expiry, epoch ms), ice_servers and transport. register-phone-call responses carry sip_uri, the SIP URI your PBX dials.

Related#