# `bird preferences list`

## Usage

```bash
bird preferences list [flags]
```

## Description

List the workspace's stated messaging preferences (consent grants and opt-outs) as a cursor page. Filter by channel, and by handle within a channel, to look up one person before messaging them.

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

## Examples

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

## Options

#### Filters

| Name                | Description                                                                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--channel`         | Return only preferences on this channel. Known values: email, sms, whatsapp (others may exist).                                                                 |
| `--handle`          | Return only preferences for this exact handle: an email address or an E.164 phone number. Requires channel, since a handle only means something on its channel. |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                |

#### 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 preferences create`](/docs/cli/reference/preferences-create) | Record a preference |
| [`bird preferences delete`](/docs/cli/reference/preferences-delete) | Delete a preference |
| [`bird preferences get`](/docs/cli/reference/preferences-get)       | Get a preference    |