Documentation
Sign inGet started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Get a call

GET
/v1/voice/calls/{call_id}
const call = await bird.voice.get("vcl_01k0p3v9wera3v6q6xw3e9y2mh");
// A call still ringing or connected carries no economics yet.
call.status; // "answered" | "no_answer" | "ringing" | …
Response200
{
  "id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
  "session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mg",
  "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "from": "+14155551234",
  "to": "+16505559876",
  "actor": {
    "id": "usr_01krdgeqcxet5s7t44vh8rt9mg",
    "type": "user"
  },
  "sip_trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg",
  "status": "answered",
  "sip_response_code": 200,
  "rejection_reason": "destination_not_enabled",
  "duration_ms": 65000,
  "pdd_ms": 850,
  "billable_ms": 60000,
  "media_quality": {
    "mos": 4.32,
    "jitter_ms": 12,
    "packet_loss_pct": 1.5,
    "round_trip_time_ms": 42
  },
  "cost": {
    "amount": "0.013000",
    "currency_code": "USD",
    "outbound_amount": "0.013000",
    "inbound_amount": null,
    "call_handling_amount": null
  }
}
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.
Parameters
call_id
string
Response Payload
id
string
required
Unique identifier for this call record.
session_id
nullable string
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.
workspace_id
string
required
direction
string
required
from
string
required
Calling party number in E.164 format.
to
string
required
Called party number in E.164 format.
actor
object
Who placed the call: the API key whose credentials it used, the integration acting for the workspace, or the user who placed it from a browser or the CLI. Absent when the call was admitted only by its source IP address, or when no actor was recorded.
Show child attributes
actor.id
string
required
Actor identifier.
actor.type
string
required
Who or what performed the action: user for a member's own session, oauth_token for a token issued to a caller on a member's behalf, api_key for a workspace API key, system for our own automation, sso for an organization's SSO connection, and service_account for a workspace's connected Integration acting with no member behind it. Open enum: new actor types may be added over time, so treat any unrecognized value as a future type rather than an error.
Possible values (may grow over time): user, api_key, oauth_token, system, sso, service_account
actor.display_name
nullable string
The label the actor is shown under: typically a member's name or email address, or the API key's name. Null when it could not be resolved.
sip_trunk_id
nullable string
Identifier of the SIP trunk that originated this call. null when no trunk is associated.
status
string
required
sip_response_code
nullable integer
Final SIP response code received from the carrier. null when no SIP response was received, for example on timeout or DNS failure.
rejection_reason
string
Why we refused the call before dialing a carrier. Absent when the call connected or failed at the carrier; see sip_response_code for the carrier response.
started_at
string
required
When the call was initiated.
answered_at
nullable string
When the call was answered (200 OK received). null for unanswered calls.
ended_at
nullable string
When the call ended (BYE or final non-2xx response). null for calls that ended abnormally without a recorded end event.
duration_ms
nullable integer
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.
pdd_ms
integer
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.
billable_ms
nullable integer
Billable duration in milliseconds, measured from answer to call end. Zero for unanswered calls, and null while the call is still in progress.
media_quality
object
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.
Show child attributes
media_quality.mos
number
required
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.
media_quality.jitter_ms
integer
required
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.
media_quality.packet_loss_pct
number
required
Percentage of audio packets that never arrived. Heard as brief gaps or clipped words, and the impairment that degrades a call fastest.
media_quality.round_trip_time_ms
integer
required
Round-trip time between the two ends, in milliseconds. It does not distort the audio. Above roughly 300 ms, the two parties start talking over each other.
cost
object
What the call cost, net of tax, at full precision, split into the components that make it up. Absent until the call has been rated; unanswered or unpriced calls have no cost.
Show child attributes
cost.amount
string
required
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
cost.currency_code
string
required
ISO 4217 currency code. Every component is denominated in this currency.
cost.outbound_amount
nullable string
required
What we charged to carry the call to the destination network, as a decimal string. null until this component is priced.
cost.inbound_amount
nullable string
required
What we charged to receive the call from the originating network, as a decimal string. Only a call that arrived at your number can carry it. null until this component is priced.
cost.call_handling_amount
nullable string
required
What we charged for handling the call itself, as a decimal string. A call is charged for handling once, however many legs it has, so only one leg's record carries it. null until this component is priced.