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

List legs

GET
/v1/voice/legs
for await (const leg of bird.voice.legs.list()) {
  console.log(leg.id, leg.status);
}
Response200
{
  "data": [
    {
      "id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
      "call_id": "vcs_01krdgeqcxet5s7t44vh8rt9mg",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "direction": "outbound",
      "from": "+14155551234",
      "to": "+16505559876",
      "actor": {
        "id": "usr_01krdgeqcxet5s7t44vh8rt9mg",
        "type": "user"
      },
      "sip_trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg",
      "sip_call_id": "3f9a1c8e7b2d4a5f@sip.example.net",
      "status": "answered",
      "sip_response_code": 200,
      "rejection_reason": "destination_not_enabled",
      "route": {
        "type": "trunk"
      },
      "tags": [
        {
          "name": "category",
          "value": "welcome"
        }
      ],
      "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,
        "recording_amount": null,
        "transcription_amount": null
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns a paginated list of the workspace's legs, ordered by start time descending.

The status filter selects where in the lifecycle you look, and any combination is a single page: in-flight statuses (ringing, in_progress), final ones, or both together. Omit it and you get completed legs, which is what this list has always returned.

A leg in flight carries no economics yet: duration_ms, billable_ms, ended_at, and cost are null until it ends. It keeps the same id throughout, so the same leg answers under one identity from the first ring to settlement.

Query Parameters

directionstring

Return only legs in this direction.

Possible values: inbound, outbound

statusarray

Return only legs with one of these statuses, comma-separated. In-flight and final statuses may be combined freely.

call_idstring

Return only legs belonging to this call, which is how the legs of one multi-party or transferred call are correlated.

sip_trunk_idstring

Return only legs carried by this SIP trunk.

fromstring

Return only legs 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 legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. Use number instead to match part of a number, or either side of the leg.

tostring

Return only legs 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 legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. Use number instead to match part of a number, or either side of the leg.

numberstring

Return only legs where the calling or called number contains this value. Matches a partial number, so a country or area-code prefix returns every leg to or from it. Combines with from/to, which match one side exactly.

tagarray

Filter by tag. Accepts name to match any record carrying that tag name, or name:value to match a specific tag pair (for example category:welcome). Repeat the parameter to add more tags. A record must match every tag listed to be returned.

started_afterstring

Return only legs that started at or after this instant, inclusive. RFC 3339 timestamp.

started_beforestring

Return only legs that started at or before this instant, inclusive. RFC 3339 timestamp.

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

Response Payload

data
array of object
required
Show child attributes
next_cursor
nullable string
required

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor
nullable string
required

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor
nullable string
required

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief