# Calls

## List calls with filters

> Query call entities with date range, status, and duration filters. Enriched with quality\_score and final\_state from call\_intelligence.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CallListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CallSummary"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"}},"type":"object","required":["items","total","has_more"],"title":"CallListResponse"},"CallSummary":{"properties":{"entity_id":{"type":"string","title":"Entity Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number"},"caller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"escalation_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escalation Status"},"turns":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turns"},"has_recording":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Recording"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"service_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Id"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"parent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Session Id"},"fork_turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fork Turn Index"}},"type":"object","required":["entity_id"],"title":"CallSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/calls":{"get":{"tags":["Calls"],"summary":"List calls with filters","description":"Query call entities with date range, status, and duration filters. Enriched with quality_score and final_state from call_intelligence.","operationId":"list-calls","parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (inclusive)","title":"Date From"},"description":"Start date (inclusive)"},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (inclusive)","title":"Date To"},"description":"End date (inclusive)"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by call status","title":"Status"},"description":"Filter by call status"},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by direction (inbound, outbound, playground, simulated)","title":"Direction"},"description":"Filter by direction (inbound, outbound, playground, simulated)"},{"name":"min_duration","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Minimum duration in seconds","title":"Min Duration"},"description":"Minimum duration in seconds"},{"name":"max_duration","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Maximum duration in seconds","title":"Max Duration"},"description":"Maximum duration in seconds"},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by service ID","title":"Service Id"},"description":"Filter by service ID"},{"name":"include_simulated","in":"query","required":false,"schema":{"type":"boolean","description":"Include simulated sessions","default":false,"title":"Include Simulated"},"description":"Include simulated sessions"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"continuation_token","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Alias for offset (pagination cursor)","title":"Continuation Token"},"description":"Alias for offset (pagination cursor)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Active calls with live intelligence

> Real-time active call list enriched with per-turn emotion, risk, and quality data from Valkey. Proxied from voice-agent.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}}},"paths":{"/v1/{workspace_id}/calls/active/intelligence":{"get":{"tags":["Calls"],"summary":"Active calls with live intelligence","description":"Real-time active call list enriched with per-turn emotion, risk, and quality data from Valkey. Proxied from voice-agent.","operationId":"list-active-calls-intelligence","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Response List-Active-Calls-Intelligence"}}}},"503":{"description":"Voice agent not configured"}}}}}}
```

## Call volume per phone number

> Aggregated call counts and durations grouped by phone number.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PhoneNumberCallVolume":{"properties":{"phone_number":{"type":"string","title":"Phone Number"},"total_calls":{"type":"integer","title":"Total Calls"},"inbound":{"type":"integer","title":"Inbound"},"outbound":{"type":"integer","title":"Outbound"},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds"},"by_date":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"By Date","default":[]}},"type":"object","required":["phone_number","total_calls","inbound","outbound"],"title":"PhoneNumberCallVolume"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/calls/phone-volume":{"get":{"tags":["Calls"],"summary":"Call volume per phone number","description":"Aggregated call counts and durations grouped by phone number.","operationId":"get-phone-call-volume","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumberCallVolume"},"title":"Response Get-Phone-Call-Volume"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Workspace call quality benchmarks

> Aggregate quality benchmarks for the workspace. Used by call detail to show 'vs workspace average' and by call list for quality context.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"WorkspaceBenchmarks":{"properties":{"avg_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Quality Score"},"p50_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Quality Score"},"p25_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25 Quality Score"},"p75_quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75 Quality Score"},"total_calls":{"type":"integer","title":"Total Calls","default":0},"avg_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Duration Seconds"},"escalation_rate":{"type":"number","title":"Escalation Rate","default":0},"quality_distribution":{"additionalProperties":{"type":"integer"},"type":"object","title":"Quality Distribution","default":{}}},"type":"object","title":"WorkspaceBenchmarks","description":"Workspace-level call quality benchmarks for contextual comparison."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/calls/benchmarks":{"get":{"tags":["Calls"],"summary":"Workspace call quality benchmarks","description":"Aggregate quality benchmarks for the workspace. Used by call detail to show 'vs workspace average' and by call list for quality context.","operationId":"get-call-benchmarks","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"description":"Lookback period in days","default":30,"title":"Days"},"description":"Lookback period in days"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceBenchmarks"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Call intelligence profile (Layer 4 narrative)

> Aggregated intelligence for a completed call: quality breakdown, key moments, and summaries. Per-turn visualization lives on the unified timeline (call detail endpoint → timeline.segments).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CallIntelligenceDetail":{"properties":{"call_id":{"type":"string","title":"Call Id"},"call_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Sid"},"direction":{"type":"string","title":"Direction","default":"inbound"},"duration_seconds":{"type":"number","title":"Duration Seconds","default":0},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score"},"quality_breakdown":{"anyOf":[{"$ref":"#/components/schemas/QualityBreakdown"},{"type":"null"}]},"key_moments":{"items":{"$ref":"#/components/schemas/KeyMoment"},"type":"array","title":"Key Moments","default":[]},"emotion_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Emotion Summary"},"risk_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Risk Summary"},"latency_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Latency Summary"},"conversation_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conversation Summary"},"tool_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Summary"},"safety_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Safety Summary"},"operator_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Operator Summary"},"completion_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completion Reason"},"final_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final State"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["call_id"],"title":"CallIntelligenceDetail","description":"Layer 4 (Narrative) intelligence for a completed call.\n\nAggregated summaries, quality breakdown, and key moments — the\ninterpretive layer. Per-turn visualization data lives on the unified\ntimeline (call detail → PlaybackTimeline.segments), not here."},"QualityBreakdown":{"properties":{"score":{"type":"number","title":"Score"},"components":{"items":{"$ref":"#/components/schemas/QualityComponent"},"type":"array","title":"Components"},"workspace_avg":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Workspace Avg"},"workspace_percentile":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Workspace Percentile"}},"type":"object","required":["score","components"],"title":"QualityBreakdown","description":"Structured breakdown of how quality score was computed."},"QualityComponent":{"properties":{"name":{"type":"string","title":"Name"},"penalty":{"type":"number","title":"Penalty"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"threshold":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Threshold"},"severity":{"type":"string","title":"Severity","default":"none"}},"type":"object","required":["name","penalty"],"title":"QualityComponent","description":"Single quality score component with penalty and context."},"KeyMoment":{"properties":{"turn":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Turn"},"type":{"type":"string","title":"Type"},"severity":{"type":"string","title":"Severity","default":"warning"},"description":{"type":"string","title":"Description"}},"type":"object","required":["type","description"],"title":"KeyMoment","description":"Notable event during the call worth highlighting."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/calls/{call_id}/intelligence":{"get":{"tags":["Calls"],"summary":"Call intelligence profile (Layer 4 narrative)","description":"Aggregated intelligence for a completed call: quality breakdown, key moments, and summaries. Per-turn visualization lives on the unified timeline (call detail endpoint → timeline.segments).","operationId":"get-call-intelligence","parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallIntelligenceDetail"}}}},"404":{"description":"Intelligence data not found for this call"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Call detail

> Full call detail including turns, escalation state, safety state, and recording info. Proxied from voice-agent, with simulation session fallback.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/calls/{call_id}":{"get":{"tags":["Calls"],"summary":"Call detail","description":"Full call detail including turns, escalation state, safety state, and recording info. Proxied from voice-agent, with simulation session fallback.","operationId":"get-call-detail","parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get-Call-Detail"}}}},"404":{"description":"Call not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```