Calls & Recordings

← Back to API Reference

---

Contents

• List calls
• Get call
• Event trace
• Outbound calls
• Manual start / end
• Recordings
• Call field reference
• Event type reference

---

GET /api/calls

Paginated call history.

Query parameters:

Parameter	Type	Default	Description
page	int	1	Page number (1-based)
page_size	int	20	Results per page (max 100)
status	string	—	ringing · in_progress · completed · failed · no_answer

Response:

{
  "calls": [ /* array of Call objects */ ],
  "total": 1250
}

---

GET /api/calls/{call_id}

Get a single call with full details: transcript, call context, per-call usage stats, and end reason.

---

GET /api/calls/{call_id}/events

Time-ordered trace of everything that happened during a call. Useful for debugging agent behaviour, latency, and tool calls.

Response:

[
  {
    "id": 1,
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "user_spoke",
    "timestamp": "2026-03-18T10:23:46.123456",
    "data": { "text": "Hello, I have a question about my order" }
  },
  {
    "id": 2,
    "event_type": "tool_called",
    "timestamp": "2026-03-18T10:23:51.456789",
    "data": { "function": "lookup_order", "args": { "order_id": "ORD-12345" } }
  }
]

---

POST /api/calls/outbound

Initiate an outbound call.

Request:

{
  "phone_number": "+919876543210",
  "agent_name": "sales-agent",
  "caller_id": "+15551234567",
  "provider": "twilio",
  "custom_parameters": {
    "customer_name": "Ravi Kumar",
    "invoice_amount": "4500"
  }
}

Field	Required	Description
phone_number	Yes	Destination in E.164 format
agent_name	Yes	Name of the agent to handle the call
caller_id	No	Caller ID to display. Falls back to provider default.
provider	No	Override telephony provider. Falls back to DB settings.
custom_parameters	No	Key-value pairs injected as call context

Response:

{
  "status": "initiated",
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "provider_response": {
    "sid": "CA...",
    "status": "queued"
  }
}

custom_parameters usage:

• substitution in the agent greeting and flow node prompts
• Injected into the LLM system prompt as call context at call start
• Passed as arguments to pre_call_tool_ids tools

---

Manual Start / End

These are for testing or non-standard telephony integrations where you manage the call lifecycle yourself.

POST /api/calls/start

Manually register a new call record.

{
  "phone_number": "+919876543210",
  "agent_name": "sales-agent",
  "direction": "inbound",
  "metadata": {}
}

POST /api/calls/end

Manually mark a call as complete.

{ "call_id": "550e8400-e29b-41d4-a716-446655440000" }

---

Recordings

GET /api/recordings/{call_id}

Stream the WAV recording for a completed call. Returns 404 if no recording exists for this call.

The response is a streaming audio/wav file — use this URL directly in an <audio> element or for download.

---

Call Field Reference

Field	Description
id	Call UUID
phone_number	Caller/callee number in E.164 format
agent_name	Agent that handled the call
direction	inbound or outbound
status	ringing · in_progress · completed · failed · no_answer
start_time	ISO 8601 when the call connected
end_time	ISO 8601 when the call ended
duration	Duration in seconds
recording_path	Path to WAV recording, if available
transcript	Full conversation with timestamps
end_reason	Why the call ended: agent_ended · user_ended · idle_timeout · error
llm_prompt_tokens	Total LLM input tokens across all turns
llm_completion_tokens	Total LLM output tokens across all turns
tts_characters	Total characters sent to TTS
metadata	Arbitrary metadata attached to the call

---

Event Type Reference

Event Type	Description
call_started	Call connected
call_ended	Call completed
user_spoke	User speech transcription (data.text)
agent_spoke	Agent response text (data.text)
tool_called	LLM invoked a tool (data.function, data.args)
tool_result	Tool returned a result (data.result)
node_entered	Flow engine entered a node (data.node_key)
node_transition	Flow engine transitioned between nodes
context_injected	Pre-call or pre-action context added to LLM
tts_started	TTS audio playback began
tts_stopped	TTS audio playback ended (includes duration)
interruption	User interrupted the agent mid-speech
ttfb_metric	Time-to-first-byte latency measurement (data.ms)
llm_usage	Token count for a single LLM turn
tts_usage	Character count for a single TTS call
call_status	Telephony provider status update
error	Pipeline error (data.message, data.context)