List calls
GET
/v1/voice/calls
bird voice listcurl -X GET "https://us1.platform.bird.com/v1/voice/calls" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"for await (const call of bird.voice.list({ status: ["ringing", "in_progress"] })) {
console.log(call.id, call.status);
}for call in client.voice.list(status=["ringing", "in_progress"]):
print(call.id, call.status)for call, err := range client.Voice.List(context.Background(), bird.VoiceListParams{
Status: []bird.VoiceCallStatus{"ringing", "in_progress"},
}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(call.Id, call.Status)
}foreach ($bird->voice->list(['status' => ['ringing', 'in_progress']]) as $call) {
echo $call->getId(), ' ', $call->getStatus(), "\n";
}Returns a paginated list of the workspace's calls, ordered by start time descending.
The status filter selects which side of the call lifecycle you get. Omit it, or pass only final statuses, and you get completed calls. Pass only the in-flight statuses (ringing, in_progress) and you get the calls happening right now. A call in flight carries no economics yet: duration_ms, billable_ms, ended_at, and cost are null until it ends, and the completed record then appears under the same id.
In-flight and completed calls are paged separately, so a request that mixes in-flight and final statuses returns a 422 validation_error.
Parámetros de consulta
direction
string
Return only calls in this direction.
Possible values: inbound, outbound
status
array
Return only calls with one of these statuses, comma-separated. The in-flight statuses (ringing, in_progress) cannot be combined with final ones in the same request.
session_id
string
Return only calls belonging to this session, which is how the legs of one multi-party or transferred call are correlated.
sip_trunk_id
string
Return only calls carried by this SIP trunk.
from
string
Return only calls placed from this calling party number, matched as a whole number rather than as a fragment. Give it in international form: +14155551234, 14155551234, and 0014155551234 all select the same calls, because a call record keeps the number exactly as the calling equipment presented it. A number given without a country code matches only calls recorded in that same form, since it names a different number in every country. Use number instead to match part of a number, or either side of the call.
to
string
Return only calls placed to this called party number, matched as a whole number rather than as a fragment. Give it in international form: +16505559876, 16505559876, and 0016505559876 all select the same calls, because a call record keeps the number exactly as the calling equipment presented it. A number given without a country code matches only calls recorded in that same form, since it names a different number in every country. Use number instead to match part of a number, or either side of the call.
number
string
Return only calls where the calling or called number contains this value. Matches a partial number, so a country or area-code prefix returns every call to or from it. Combines with from/to, which match one side exactly.
started_after
string
Return only calls that started at or after this instant, inclusive. RFC 3339 timestamp.
started_before
string
Return only calls that started at or before this instant, inclusive. RFC 3339 timestamp.
limit
integer
Maximum number of items to return per page.
starting_after
string
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_before
string
Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.
Carga de respuesta
data
array of object
obligatorio
Mostrar atributos secundarios
data.id
string
obligatorio
Unique identifier for this call record.
data.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.
data.workspace_id
string
obligatorio
data.direction
object
obligatorio
data.from
string
obligatorio
Calling party number in E.164 format.
data.to
string
obligatorio
Called party number in E.164 format.
data.sip_trunk_id
nullable string
Identifier of the SIP trunk that originated this call. Null when no trunk is associated.
data.status
object
obligatorio
data.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.
data.rejection_reason
object
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.
data.started_at
string
obligatorio
When the call was initiated.
data.answered_at
nullable string
When the call was answered (200 OK received). Null for unanswered calls.
data.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.
data.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.
data.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.
data.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.
data.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.
Mostrar atributos secundarios
data.media_quality.mos
number
obligatorio
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.
data.media_quality.jitter_ms
integer
obligatorio
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.
data.media_quality.packet_loss_pct
number
obligatorio
Percentage of audio packets that never arrived. Heard as brief gaps or clipped words, and the impairment that degrades a call fastest.
data.media_quality.round_trip_time_ms
integer
obligatorio
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.
data.cost
object
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.
Mostrar atributos secundarios
data.cost.amount
string
obligatorio
Decimal amount as a string, in major currency units.
data.cost.currency_code
string
obligatorio
ISO 4217 currency code.
next_cursor
nullable string
obligatorio
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
obligatorio
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
obligatorio
Refresh anchor. Pass back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.