# `bird voice legs list`

## Usage

```bash
bird voice legs list [flags]
```

## Description

List the workspace's legs, newest first. Filter to `ringing`/`in_progress` for the legs in progress right now, to final statuses for completed records, or to any mix of the two. Use `from`/`to` for one known party number in international form, and `number` to search either side by fragment. These are per-leg records and do not include aggregate rates or totals. Use `bird voice legs get` to follow one leg to settlement.

Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.

## Procedure

Step 1 of 9 of "Watch voice legs and find out why one was refused". Next: bird voice legs get.

## Examples

```bash
bird voice legs list
bird voice legs list | jq -r '.data[].id'
bird voice legs list --limit 50 --starting-after <cursor>
```

## Options

#### Filters

| Name                | Description                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--call-id`         | Return only legs belonging to this call, which is how the legs of one multi-party or transferred call are correlated.                                                                                                                                                                                                                                                                                                            |
| `--direction`       | Return only legs in this direction. Possible values: inbound, outbound.                                                                                                                                                                                                                                                                                                                                                          |
| `--from`            | 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. |
| `--number`          | 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.                                                                                                                                                                                                        |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                                                                                                                                                                                                                                                                                 |
| `--sip-trunk-id`    | Return only legs carried by this SIP trunk.                                                                                                                                                                                                                                                                                                                                                                                      |
| `--started-after`   | Return only legs that started at or after this instant, inclusive. RFC 3339 timestamp.                                                                                                                                                                                                                                                                                                                                           |
| `--started-before`  | Return only legs that started at or before this instant, inclusive. RFC 3339 timestamp.                                                                                                                                                                                                                                                                                                                                          |
| `--status <value>…` | Return only legs with one of these statuses, comma-separated. In-flight and final statuses may be combined freely. Possible values: answered, no\_answer, busy, canceled, failed, rejected, unknown, ringing, in\_progress.                                                                                                                                                                                                      |
| `--tag <value>…`    | 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.                                                                                                                                                                                   |
| `--to`              | 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.    |

#### Pagination

| Name               | Description                                                                                                                                                                                                                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ending-before`  | 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. |
| `--limit <n>`      | Maximum number of items to return per page.                                                                                                                                                                                                                                                                                                             |
| `--starting-after` | Cursor from the next\_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.                                                                                                                                                                                                          |

## Related

| Name                                                        | Description |
| ----------------------------------------------------------- | ----------- |
| [`bird voice legs get`](/docs/cli/reference/voice-legs-get) | Get a leg   |

## Related resources

- [What is a voice API?](/explained/voice/what-is-a-voice-api) (answer)
- [Voice](/products/voice) (product)
- [Voice overview](/docs/guides/voice/overview) (docs)

[Get an implementation brief](/learn/workspace?topic=voice)