> For the complete documentation index, see [llms.txt](https://api-docs.helloaviary.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.helloaviary.ai/calls.md).
# Calls
Individual outbound/inbound call records (calls + calls\_auditor). External callers see a curated projection plus a locked auditor allowlist; internal callers see every column on both tables.
## Get a call (external projection)
> Returns the safe-for-external projection of a single call. Telephony-\
> internal fields (twilio\_sid, vcon\_uuid, pid), raw transcripts, and the\
> raw grade JSONB are filtered out. The auditor allowlist is nested under\
> \`auditor\` and may be null if the auditor row hasn't been written yet.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"Calls","description":"Individual outbound/inbound call records (calls + calls_auditor).\nExternal callers see a curated projection plus a locked auditor allowlist;\ninternal callers see every column on both tables.\n"}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"CallExternalResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/CallExternal"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CallExternal":{"type":"object","required":["id","external_id","environment","created_at","updated_at"],"description":"External projection of a call. Excludes telephony-internal fields\n(twilio_sid, vcon_uuid, pid), raw transcripts, raw grade JSONB, A/B\ntesting internals, and soft-delete metadata.\n","properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"use_case_id":{"type":"integer","format":"int64","nullable":true},"customer_id":{"type":"integer","format":"int64","nullable":true},"call_attempt_date":{"type":"string","format":"date-time","nullable":true,"description":"Date the call is scheduled to happen (DATE column in DB, returned\nas RFC3339 with 00:00:00Z component). Editability rule is keyed\noff this field; see §3 of the build plan.\n"},"actual_call_date":{"type":"string","format":"date-time","nullable":true},"call_attempt_number":{"type":"integer","nullable":true},"call_attempt_time":{"type":"integer","nullable":true},"call_length":{"type":"number","format":"double","nullable":true},"escalated":{"type":"boolean","nullable":true},"successful":{"type":"boolean","nullable":true},"connected":{"type":"boolean","nullable":true},"screening_call":{"type":"boolean","nullable":true},"attempted_call":{"type":"boolean","nullable":true},"call_recording_link":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"bot_voice_gender":{"type":"string","nullable":true},"is_rescheduled":{"type":"boolean","nullable":true},"rescheduled_time":{"type":"string","format":"date-time","nullable":true},"inbound":{"type":"boolean","nullable":true},"pii_redacted_transcript":{"nullable":true,"description":"PII-redacted transcript JSONB. Shape depends on the upstream pipeline."},"pii_redacted_audio":{"type":"string","nullable":true},"environment":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"auditor":{"allOf":[{"$ref":"#/components/schemas/CallAuditorExternal"}],"nullable":true,"description":"Null until the auditor row has been written for this call."}}},"CallAuditorExternal":{"type":"object","description":"Locked allowlist of auditor fields exposed to external callers (§2.2.1\nof the build plan). Any field outside this set is internal-only —\nnew fields land here only after explicit approval.\n","properties":{"true_connected":{"type":"boolean","nullable":true},"passed_intro":{"type":"boolean","nullable":true},"agent_spoke_at_all":{"type":"boolean","nullable":true},"app_errors":{"type":"boolean","nullable":true},"agent_stopped_responding":{"type":"boolean","nullable":true},"member_frustration":{"type":"string","nullable":true},"roundup":{"type":"string","nullable":true},"dnc":{"type":"boolean","nullable":true,"description":"Customer-level Do-Not-Call flag from the auditor (NOT dnc_org)."},"complete_conversation":{"type":"boolean","nullable":true},"choppy_score":{"type":"integer","nullable":true},"wrong_number":{"type":"boolean","nullable":true},"illogical_score":{"type":"integer","nullable":true},"identified_language":{"type":"string","nullable":true},"language_barrier":{"type":"boolean","nullable":true},"contact_sentiment":{"type":"string","nullable":true},"voicemail_box_full":{"type":"boolean","nullable":true},"ran_into_call_screener":{"type":"boolean","nullable":true},"connection_issues":{"type":"boolean","nullable":true},"overall_outcome_label":{"type":"string","nullable":true},"unauthorized_promise":{"type":"boolean","nullable":true},"compliance_risk_flag":{"type":"boolean","nullable":true}}},"Meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Unique ID for this request. Echoed in the `X-Request-ID` response\nheader. Send this back to support to debug a specific call.\n"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/v1/calls/{id}":{"get":{"summary":"Get a call (external projection)","description":"Returns the safe-for-external projection of a single call. Telephony-\ninternal fields (twilio_sid, vcon_uuid, pid), raw transcripts, and the\nraw grade JSONB are filtered out. The auditor allowlist is nested under\n`auditor` and may be null if the auditor row hasn't been written yet.\n","operationId":"getCallExternalV1","tags":["Calls"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallExternalResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Call not found (or soft-deleted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Cancel a scheduled call (external, soft-delete)
> Soft-deletes the call by stamping \`deleted\_at = NOW()\`. The\
> \`calls\_auditor\` row, if any, is left untouched. List/GET endpoints\
> will hide the row going forward (internal callers can opt back in\
> with \`?include\_deleted=true\`).\
> \
> The same scheduled-state predicate as PATCH applies — once a call\
> has started, it cannot be cancelled.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"Calls","description":"Individual outbound/inbound call records (calls + calls_auditor).\nExternal callers see a curated projection plus a locked auditor allowlist;\ninternal callers see every column on both tables.\n"}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/v1/calls/{id}":{"delete":{"summary":"Cancel a scheduled call (external, soft-delete)","description":"Soft-deletes the call by stamping `deleted_at = NOW()`. The\n`calls_auditor` row, if any, is left untouched. List/GET endpoints\nwill hide the row going forward (internal callers can opt back in\nwith `?include_deleted=true`).\n\nThe same scheduled-state predicate as PATCH applies — once a call\nhas started, it cannot be cancelled.\n","operationId":"deleteCallExternalV1","tags":["Calls"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Call not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Call has already started; not deletable. code: call_already_started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Update a call (external)
> Partial update — only \`call\_attempt\_date\` is editable from the\
> external surface. Any other field returns 400 \`field\_not\_editable\`.\
> \
> The call must also still be in a "scheduled" state per §3 of the\
> build plan:\
> \- \`call\_attempt\_date > today (UTC)\`, OR\
> \- \`call\_attempt\_date == today (UTC)\` AND \`twilio\_sid IS NULL\` AND\
> \`attempted\_call IS NULL\`.\
> \
> If the call has already started (or already happened), the response\
> is 409 \`call\_already\_started\` and nothing is written.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"Calls","description":"Individual outbound/inbound call records (calls + calls_auditor).\nExternal callers see a curated projection plus a locked auditor allowlist;\ninternal callers see every column on both tables.\n"}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"CallPatchRequest":{"type":"object","required":["call_attempt_date"],"description":"External PATCH allowlist (§3.1): only `call_attempt_date` is editable.\nAny other field returns 400 `field_not_editable`. Sending an explicit\nnull returns 400 — to clear the schedule, DELETE the call instead.\nThe call must also be in a \"scheduled\" state (§3); otherwise 409\n`call_already_started`.\n","properties":{"call_attempt_date":{"type":"string","description":"New scheduled date. Accepts either YYYY-MM-DD (preferred — matches\nthe underlying DATE column) or full RFC3339.\n"}}},"CallExternalResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/CallExternal"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CallExternal":{"type":"object","required":["id","external_id","environment","created_at","updated_at"],"description":"External projection of a call. Excludes telephony-internal fields\n(twilio_sid, vcon_uuid, pid), raw transcripts, raw grade JSONB, A/B\ntesting internals, and soft-delete metadata.\n","properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"use_case_id":{"type":"integer","format":"int64","nullable":true},"customer_id":{"type":"integer","format":"int64","nullable":true},"call_attempt_date":{"type":"string","format":"date-time","nullable":true,"description":"Date the call is scheduled to happen (DATE column in DB, returned\nas RFC3339 with 00:00:00Z component). Editability rule is keyed\noff this field; see §3 of the build plan.\n"},"actual_call_date":{"type":"string","format":"date-time","nullable":true},"call_attempt_number":{"type":"integer","nullable":true},"call_attempt_time":{"type":"integer","nullable":true},"call_length":{"type":"number","format":"double","nullable":true},"escalated":{"type":"boolean","nullable":true},"successful":{"type":"boolean","nullable":true},"connected":{"type":"boolean","nullable":true},"screening_call":{"type":"boolean","nullable":true},"attempted_call":{"type":"boolean","nullable":true},"call_recording_link":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"bot_voice_gender":{"type":"string","nullable":true},"is_rescheduled":{"type":"boolean","nullable":true},"rescheduled_time":{"type":"string","format":"date-time","nullable":true},"inbound":{"type":"boolean","nullable":true},"pii_redacted_transcript":{"nullable":true,"description":"PII-redacted transcript JSONB. Shape depends on the upstream pipeline."},"pii_redacted_audio":{"type":"string","nullable":true},"environment":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"auditor":{"allOf":[{"$ref":"#/components/schemas/CallAuditorExternal"}],"nullable":true,"description":"Null until the auditor row has been written for this call."}}},"CallAuditorExternal":{"type":"object","description":"Locked allowlist of auditor fields exposed to external callers (§2.2.1\nof the build plan). Any field outside this set is internal-only —\nnew fields land here only after explicit approval.\n","properties":{"true_connected":{"type":"boolean","nullable":true},"passed_intro":{"type":"boolean","nullable":true},"agent_spoke_at_all":{"type":"boolean","nullable":true},"app_errors":{"type":"boolean","nullable":true},"agent_stopped_responding":{"type":"boolean","nullable":true},"member_frustration":{"type":"string","nullable":true},"roundup":{"type":"string","nullable":true},"dnc":{"type":"boolean","nullable":true,"description":"Customer-level Do-Not-Call flag from the auditor (NOT dnc_org)."},"complete_conversation":{"type":"boolean","nullable":true},"choppy_score":{"type":"integer","nullable":true},"wrong_number":{"type":"boolean","nullable":true},"illogical_score":{"type":"integer","nullable":true},"identified_language":{"type":"string","nullable":true},"language_barrier":{"type":"boolean","nullable":true},"contact_sentiment":{"type":"string","nullable":true},"voicemail_box_full":{"type":"boolean","nullable":true},"ran_into_call_screener":{"type":"boolean","nullable":true},"connection_issues":{"type":"boolean","nullable":true},"overall_outcome_label":{"type":"string","nullable":true},"unauthorized_promise":{"type":"boolean","nullable":true},"compliance_risk_flag":{"type":"boolean","nullable":true}}},"Meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Unique ID for this request. Echoed in the `X-Request-ID` response\nheader. Send this back to support to debug a specific call.\n"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/v1/calls/{id}":{"patch":{"summary":"Update a call (external)","description":"Partial update — only `call_attempt_date` is editable from the\nexternal surface. Any other field returns 400 `field_not_editable`.\n\nThe call must also still be in a \"scheduled\" state per §3 of the\nbuild plan:\n - `call_attempt_date > today (UTC)`, OR\n - `call_attempt_date == today (UTC)` AND `twilio_sid IS NULL` AND\n `attempted_call IS NULL`.\n\nIf the call has already started (or already happened), the response\nis 409 `call_already_started` and nothing is written.\n","operationId":"patchCallExternalV1","tags":["Calls"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallPatchRequest"}}}},"responses":{"200":{"description":"OK — returns the post-update call (external projection).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallExternalResponse"}}}},"400":{"description":"Bad body, unknown field, or unparseable date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Call not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Call has already started; not editable. code: call_already_started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## List calls (internal)
> Paginated list of calls with optional filters. Returns the full\
> internal projection per row (no auditor join — fetch the per-row\
> endpoint for that). Soft-deleted rows are hidden by default; pass\
> \`include\_deleted=true\` to see them.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"Calls","description":"Individual outbound/inbound call records (calls + calls_auditor).\nExternal callers see a curated projection plus a locked auditor allowlist;\ninternal callers see every column on both tables.\n"},{"name":"Internal","description":"Internal-only endpoints. Forbidden for external client keys."}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"parameters":{"Limit":{"name":"limit","in":"query","required":false,"description":"Page size (1-500). Default 50.","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned in `meta.page.next_cursor` from the previous page.\nCurrently the last id of the previous page; treat as opaque.\n","schema":{"type":"string"}}},"schemas":{"CallListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CallInternal"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"CallInternal":{"type":"object","required":["id","external_id","environment","organization_id","created_at","updated_at"],"description":"Full internal projection of a call — every column on the calls table.\nIncludes telephony-internal fields, raw grade/transcripts JSONB, and\nsoft-delete metadata.\n","properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"client_id":{"type":"integer","format":"int64","nullable":true},"use_case_id":{"type":"integer","format":"int64","nullable":true},"customer_id":{"type":"integer","format":"int64","nullable":true},"call_attempt_date":{"type":"string","format":"date-time","nullable":true},"actual_call_date":{"type":"string","format":"date-time","nullable":true},"call_attempt_number":{"type":"integer","nullable":true},"twilio_sid":{"type":"string","nullable":true},"call_length":{"type":"number","format":"double","nullable":true},"escalated":{"type":"boolean","nullable":true},"successful":{"type":"boolean","nullable":true},"connected":{"type":"boolean","nullable":true},"screening_call":{"type":"boolean","nullable":true},"attempted_call":{"type":"boolean","nullable":true},"call_recording_link":{"type":"string","nullable":true},"grade":{"nullable":true,"description":"Raw grading JSONB"},"reason":{"type":"string","nullable":true},"bot_voice_gender":{"type":"string","nullable":true},"pid":{"type":"string","nullable":true},"is_rescheduled":{"type":"boolean","nullable":true},"rescheduled_time":{"type":"string","format":"date-time","nullable":true},"inbound":{"type":"boolean","nullable":true},"vcon_uuid":{"type":"string","nullable":true},"call_attempt_time":{"type":"integer","nullable":true},"transcripts":{"nullable":true,"description":"Raw transcript JSONB"},"pii_redacted_transcript":{"nullable":true},"pii_redacted_audio":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"environment":{"type":"string"},"organization_id":{"type":"string"},"config_variant":{"type":"string","nullable":true},"config_file_used":{"type":"string","nullable":true}}},"ListMeta":{"type":"object","required":["request_id","page"],"properties":{"request_id":{"type":"string","format":"uuid"},"page":{"$ref":"#/components/schemas/PageInfo"}}},"PageInfo":{"type":"object","required":["limit"],"properties":{"limit":{"type":"integer"},"next_cursor":{"type":"string","description":"Pass back as `?cursor=` to get the next page. Absent on the last page."}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/internal/v1/calls":{"get":{"summary":"List calls (internal)","description":"Paginated list of calls with optional filters. Returns the full\ninternal projection per row (no auditor join — fetch the per-row\nendpoint for that). Soft-deleted rows are hidden by default; pass\n`include_deleted=true` to see them.\n","operationId":"listCallsInternalV1","tags":["Calls","Internal"],"parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"use_case_id","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"customer_id","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"from","in":"query","required":false,"description":"Lower bound on `call_attempt_date` (inclusive). YYYY-MM-DD or RFC3339.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Upper bound on `call_attempt_date` (inclusive). YYYY-MM-DD or RFC3339.","schema":{"type":"string"}},{"name":"include_deleted","in":"query","required":false,"description":"If `true`, soft-deleted rows are included in the result set.","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallListResponse"}}}},"400":{"description":"Bad query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"External key cannot reach internal scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Get a call (internal, full surface + auditor)
> Returns every column on the calls table, plus a fully-populated\
> auditor row if one exists. Soft-deleted rows are hidden by default;\
> pass \`include\_deleted=true\` to fetch one anyway.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"Calls","description":"Individual outbound/inbound call records (calls + calls_auditor).\nExternal callers see a curated projection plus a locked auditor allowlist;\ninternal callers see every column on both tables.\n"},{"name":"Internal","description":"Internal-only endpoints. Forbidden for external client keys."}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"CallInternalResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["call"],"properties":{"call":{"$ref":"#/components/schemas/CallInternal"},"auditor":{"allOf":[{"$ref":"#/components/schemas/CallAuditorInternal"}],"nullable":true}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"CallInternal":{"type":"object","required":["id","external_id","environment","organization_id","created_at","updated_at"],"description":"Full internal projection of a call — every column on the calls table.\nIncludes telephony-internal fields, raw grade/transcripts JSONB, and\nsoft-delete metadata.\n","properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"client_id":{"type":"integer","format":"int64","nullable":true},"use_case_id":{"type":"integer","format":"int64","nullable":true},"customer_id":{"type":"integer","format":"int64","nullable":true},"call_attempt_date":{"type":"string","format":"date-time","nullable":true},"actual_call_date":{"type":"string","format":"date-time","nullable":true},"call_attempt_number":{"type":"integer","nullable":true},"twilio_sid":{"type":"string","nullable":true},"call_length":{"type":"number","format":"double","nullable":true},"escalated":{"type":"boolean","nullable":true},"successful":{"type":"boolean","nullable":true},"connected":{"type":"boolean","nullable":true},"screening_call":{"type":"boolean","nullable":true},"attempted_call":{"type":"boolean","nullable":true},"call_recording_link":{"type":"string","nullable":true},"grade":{"nullable":true,"description":"Raw grading JSONB"},"reason":{"type":"string","nullable":true},"bot_voice_gender":{"type":"string","nullable":true},"pid":{"type":"string","nullable":true},"is_rescheduled":{"type":"boolean","nullable":true},"rescheduled_time":{"type":"string","format":"date-time","nullable":true},"inbound":{"type":"boolean","nullable":true},"vcon_uuid":{"type":"string","nullable":true},"call_attempt_time":{"type":"integer","nullable":true},"transcripts":{"nullable":true,"description":"Raw transcript JSONB"},"pii_redacted_transcript":{"nullable":true},"pii_redacted_audio":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"deleted_at":{"type":"string","format":"date-time","nullable":true},"environment":{"type":"string"},"organization_id":{"type":"string"},"config_variant":{"type":"string","nullable":true},"config_file_used":{"type":"string","nullable":true}}},"CallAuditorInternal":{"type":"object","required":["id","external_id","client_id","customer_id","call_id","organization_id","created_at","updated_at"],"description":"Full internal projection of a calls_auditor row.","properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"client_id":{"type":"integer","format":"int64"},"use_case_id":{"type":"integer","format":"int64","nullable":true},"customer_id":{"type":"integer","format":"int64"},"call_id":{"type":"integer","format":"int64"},"reasoning":{"type":"string","nullable":true},"agent_spoke_of_programs":{"type":"boolean","nullable":true},"true_connected":{"type":"boolean","nullable":true},"passed_intro":{"type":"boolean","nullable":true},"aviary_success":{"type":"boolean","nullable":true},"notes":{"type":"string","nullable":true},"on_call_issue":{"type":"string","nullable":true},"marked_connected_actually_voicemail":{"type":"boolean","nullable":true},"marked_voicemail_actually_connected":{"type":"boolean","nullable":true},"agent_spoke_at_all":{"type":"boolean","nullable":true},"app_errors":{"type":"boolean","nullable":true},"agent_stopped_responding":{"type":"boolean","nullable":true},"member_asked_to_speak_to_human":{"type":"boolean","nullable":true},"waveform_pattern":{"type":"string","nullable":true},"waveform_reason":{"type":"string","nullable":true},"agent_friendly":{"type":"boolean","nullable":true},"repetition_score":{"type":"string","nullable":true},"member_frustration":{"type":"string","nullable":true},"roundup":{"type":"string","nullable":true},"dnc":{"type":"boolean","nullable":true},"avg_response_time":{"type":"number","format":"double","nullable":true},"complete_conversation":{"type":"boolean","nullable":true},"actually_voicemail":{"type":"boolean","nullable":true},"persuasion_score":{"type":"integer","nullable":true},"suspicious_of_ai":{"type":"boolean","nullable":true},"asked_question":{"type":"boolean","nullable":true},"question_summary":{"type":"string","nullable":true},"background_noise_score":{"type":"integer","nullable":true},"choppy_score":{"type":"integer","nullable":true},"agent_did_not_answer_q":{"type":"boolean","nullable":true},"dnc_org":{"type":"boolean","nullable":true},"wrong_number":{"type":"boolean","nullable":true},"compliance_risk_flag":{"type":"boolean","nullable":true},"unauthorized_promise":{"type":"boolean","nullable":true},"overall_outcome_label":{"type":"string","nullable":true},"connection_issues":{"type":"boolean","nullable":true},"ran_into_call_screener":{"type":"boolean","nullable":true},"voicemail_box_full":{"type":"boolean","nullable":true},"contact_sentiment":{"type":"string","nullable":true},"language_barrier":{"type":"boolean","nullable":true},"identified_language":{"type":"string","nullable":true},"needs_review":{"type":"boolean","nullable":true},"needs_review_reason":{"type":"string","nullable":true},"illogical_score":{"type":"integer","nullable":true},"compliance":{"nullable":true,"description":"Raw compliance JSONB"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"organization_id":{"type":"string"}}},"Meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Unique ID for this request. Echoed in the `X-Request-ID` response\nheader. Send this back to support to debug a specific call.\n"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/internal/v1/calls/{id}":{"get":{"summary":"Get a call (internal, full surface + auditor)","description":"Returns every column on the calls table, plus a fully-populated\nauditor row if one exists. Soft-deleted rows are hidden by default;\npass `include_deleted=true` to fetch one anyway.\n","operationId":"getCallInternalV1","tags":["Calls","Internal"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallInternalResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"External key cannot reach internal scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://api-docs.helloaviary.ai/calls.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.