<Intro>

<EndpointHeader />

<Description>

Returns a single call at any point in its lifecycle. A call that is still ringing or connected answers with its in-flight `status` and no economics: `duration_ms`, `billable_ms`, `ended_at`, and `cost` fill in once it ends, at this same URL. Returns a 404 `not_found_error` if the call does not exist in the workspace.

</Description>

</Intro>

<Payload kind="response">

<Field name="id" type="string" required>

<Description>

Unique identifier for this call record.

</Description>

</Field>

<Field name="session_id" type="nullable string">

<Description>

Session identifier shared across all legs of a multi-party or transferred call. Use this to correlate related call records. Null when session correlation is not available for the call.

</Description>

</Field>

<Field name="workspace_id" type="string" required />

<Field name="direction" type="object" required />

<Field name="from" type="string" required>

<Description>

Calling party number in E.164 format.

</Description>

</Field>

<Field name="to" type="string" required>

<Description>

Called party number in E.164 format.

</Description>

</Field>

<Field name="sip_trunk_id" type="nullable string">

<Description>

Identifier of the SIP trunk that originated this call. Null when no trunk is associated.

</Description>

</Field>

<Field name="status" type="object" required />

<Field name="sip_response_code" type="nullable integer">

<Description>

Final SIP response code received from the carrier. Null when no SIP response was received, for example on timeout or DNS failure.

</Description>

</Field>

<Field name="rejection_reason" type="object">

<Description>

Why Bird refused the call before dialing a carrier. Absent when Bird did not refuse it, meaning the call either connected or it failed at the carrier, where `sip_response_code` is the whole story.

</Description>

</Field>

<Field name="started_at" type="string" required>

<Description>

When the call was initiated.

</Description>

</Field>

<Field name="answered_at" type="nullable string">

<Description>

When the call was answered (200 OK received). Null for unanswered calls.

</Description>

</Field>

<Field name="ended_at" type="nullable string">

<Description>

When the call ended (BYE or final non-2xx response). Null for calls that ended abnormally without a recorded end event.

</Description>

</Field>

<Field name="duration_ms" type="nullable integer">

<Description>

Total call duration in milliseconds, measured from the first INVITE to the BYE or final response. Null while the call is still in progress and has no final duration yet.

</Description>

</Field>

<Field name="pdd_ms" type="integer">

<Description>

Post-dial delay in milliseconds: how long the caller heard nothing between dialing and the phone starting to ring at the other end. High values are what callers experience as the call "not going through". Absent when the call never rang, either because it failed first or because the carrier answered it immediately.

</Description>

</Field>

<Field name="billable_ms" type="nullable integer">

<Description>

Billable duration in milliseconds, measured from answer to call end. Zero for unanswered calls, and null while the call is still in progress.

</Description>

</Field>

<Field name="media_quality" type="object">

<Description>

How the audio sounded, as opposed to whether the call connected. Absent when the call carried no audio, or when the far end reported nothing to measure from.

</Description>

<FieldChildren kind="response">

<Field name="mos" type="number" prefix="media_quality." required>

<Description>

Mean opinion score, the single number for how the call sounded, from 1 (unintelligible) to 5 (as good as being in the same room). Anything at or above 4.0 is what most people would call a clear line, and below 3.5 is where callers start asking each other to repeat themselves. The three other fields are the impairments that move it.

</Description>

</Field>

<Field name="jitter_ms" type="integer" prefix="media_quality." required>

<Description>

Variation in the arrival time of the audio packets, in milliseconds. Audio arriving unevenly is heard as choppiness even when no packets are lost at all.

</Description>

</Field>

<Field name="packet_loss_pct" type="number" prefix="media_quality." required>

<Description>

Percentage of audio packets that never arrived. Heard as brief gaps or clipped words, and the impairment that degrades a call fastest.

</Description>

</Field>

<Field name="round_trip_time_ms" type="integer" prefix="media_quality." required>

<Description>

Round-trip time between the two ends, in milliseconds. It does not distort the audio, but above roughly 300 ms the two parties start talking over each other.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="cost" type="object">

<Description>

Amount billed for this call, net of tax, at full precision. Absent until the call has been rated; unanswered or unpriced calls have no cost.

</Description>

<FieldChildren kind="response">

<Field name="amount" type="string" prefix="cost." required>

<Description>

Decimal amount as a string, in major currency units.

</Description>

</Field>

<Field name="currency_code" type="string" prefix="cost." required>

<Description>

ISO 4217 currency code.

</Description>

</Field>

</FieldChildren>

</Field>

</Payload>