# `bird numbers list`

## Usage

```bash
bird numbers list [flags]
```

## Description

Pages the numbers allocated to the workspace, dedicated and shared alike. Narrows on country, type, prefix and capability, so one number is reached without walking every page.

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

## Examples

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

## Options

#### Filters

| Name                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--capabilities <v1,v2,…>` | Filter by channel capability. Repeat the parameter to require several at once: capabilities=sms&capabilities=voice returns only numbers that support both. Known values: sms, voice (others may exist).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--country-code`           | Filter by the country a number belongs to, as an ISO 3166-1 alpha-2 code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--number`                 | Return only the number matching these digits. Give a full number with its country code, however your own records spell it: +12025550188, 12025550188, 0012025550188, and +1 202 555 0188 all resolve to the same number. Spacing and punctuation are fine once a leading + or 00 marks the country code, or when country_code names the country; a grouped spelling without either is refused rather than guessed at, and a national spelling (bare digits without the country code) matches only when country_code names the country. A short code is matched on its bare digits instead, and since the same short code can be allocated in more than one country, pass country_code alongside it to name which one. This filter narrows the list like the others rather than replacing them, so a country or capability filter still applies. To match a range of numbers rather than one, use prefix. |
| `--number-type`            | Return only allocated numbers of this physical type after applying the country and prefix filters. Known values: mobile, local, national, short_code, short_code_fteu, toll_free (others may exist).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--prefix`                 | Return only numbers that start with these digits, matched right after the country dial code: with country_code=US, prefix=212 returns the +1 212 area-code numbers allocated to you. Digits only, and country_code is required alongside it, since the digits are national ones. Leave out the country dial code and any national dialing prefix such as a leading 0. Short codes never match a prefix search.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--response-schema`        | Print the fields this command returns, then exit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### Pagination

| Name               | Description                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ending-before`  | Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. |
| `--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 numbers get`](/docs/cli/reference/numbers-get)         | Get an allocated number    |
| [`bird numbers release`](/docs/cli/reference/numbers-release) | Release a dedicated number |