--- title: "bird esim list" description: "List eSIMs" canonical: "https://bird.com/docs/cli/reference/esim-list" --- # `bird esim list` ## Usage ```bash bird esim list [flags] ``` ## Description List the workspace's eSIMs, newest first, as a cursor page ({data, next\_cursor, ...}). Filter by status, iccid, or tag, or search by iccid\_prefix, display\_name, or phone\_number. Each row is a compact summary; fetch a single eSIM for its packages and balances. Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after. ## Examples ```bash bird esim list bird esim list | jq -r '.data[].id' bird esim list --limit 50 --starting-after ``` ## Options #### Filters | Name | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--created-after` | Limits the response to resources created at or after this timestamp. Combine it with created\_before to select a time window. Use an RFC 3339 timestamp with a timezone offset. | | `--created-before` | Limits the response to resources created before this timestamp. Combine it with created\_after to select a time window. Use an RFC 3339 timestamp with a timezone offset. | | `--display-name` | Keep only eSIMs whose display\_name contains this text, ignoring case. An eSIM you have not named has no display\_name, so it never matches. | | `--iccid` | Filter by ICCID (exact match). | | `--iccid-prefix` | Keep only eSIMs whose ICCID starts with these digits. Use it when you hold only the first part of an ICCID. Pass iccid instead when you hold the whole number. | | `--mode` | Keep only eSIMs created in this mode. Without it, both live and test eSIMs are returned. Possible values: live, test. | | `--phone-number` | Keep only eSIMs whose mobile network has reported this phone number, matched as a whole number rather than as a fragment. Give it in international form, with or without the leading +: +31612345678 and 31612345678 select the same eSIMs. An eSIM matches on any number its mobile network has ever reported for the profile, so a number that has since moved on still finds the eSIM that held it. An eSIM whose number no network has reported yet never matches. | | `--response-schema` | Print the fields this command returns, then exit | | `--status …` | Keep only eSIMs whose current status matches; repeat the parameter to match any of several. Possible values: provisioning, ready, activating, active, suspending, suspended, resuming, releasing, released, expired, failed. | | `--subscriber-id` | Return eSIMs assigned to this subscriber. | | `--tag …` | Filter by tag. Accepts name to match any eSIM carrying that tag name, or name:value to match a specific tag pair (e.g. trip:summer). A trailing colon (name:) matches the name alone, the same as name. A term with an empty name is rejected. Repeat the parameter to AND-combine several tag filters. | #### 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 ` | Maximum number of items to return per page. Allowed range: 1 to 100. | | `--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 esim compatible-offers`](/docs/cli/reference/esim-compatible-offers) | List offers an eSIM can take | | [`bird esim get`](/docs/cli/reference/esim-get) | Get an eSIM | | [`bird esim release`](/docs/cli/reference/esim-release) | Release an eSIM | | [`bird esim resume`](/docs/cli/reference/esim-resume) | Resume an eSIM | | [`bird esim suspend`](/docs/cli/reference/esim-suspend) | Suspend an eSIM | | [`bird esim update`](/docs/cli/reference/esim-update) | Update an eSIM | ## Related resources - [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer) - [Build your first integration](/learn/paths/integration) (course) - [Send your first email](/docs/get-started/send-your-first-email) (docs) [Get an implementation brief](/learn/workspace?topic=api-basics)