---
title: "List eSIMs"
canonical: "https://bird.com/docs/api/reference/list-esims"
---

# List eSIMs

`GET /v1/esim/sims`

Returns your workspace's eSIMs as a cursor-paginated list, newest first.
Filter by lifecycle `status`, exact `iccid`, tag, or creation time;
pass the response's `next_cursor` back as `starting_after` to fetch the
next page.

To find an eSIM you cannot name by its full ICCID, search on
`iccid_prefix`, `display_name`, or `phone_number`. Each searches a
different identifier and each combines with the filters above, narrowing
the list rather than widening it. Searching never reaches outside the
workspace the request is scoped to, so an eSIM belonging to another
workspace is absent from the results rather than reported as forbidden.

## Code samples

**CLI**

```sh
bird esim list
```

Examples: [CLI](/docs/api/reference/list-esims.cli.md) · [MCP](/docs/api/reference/list-esims.mcp.md) · [cURL](/docs/api/reference/list-esims.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "subscriber_id": "esub_01krdgeqcxet5s7t44vh8rt9mg",
      "id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "provisioning",
      "mode": "live",
      "iccid": "8944500212345678912",
      "phone_number": "+31612345678"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Query parameters

- `limit` (integer): Maximum number of items to return per page.
- `starting_after` (string): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string): 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.
- `subscriber_id` (string): Return eSIMs assigned to this subscriber.
- `created_after` (string): 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` (string): 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.
- `status` (array): Keep only eSIMs whose current `status` matches; repeat the parameter to match any of several.
- `iccid` (string): Filter by ICCID (exact match).
- `mode` (string)

  Keep only eSIMs created in this mode. Without it, both live and test eSIMs are returned.

  Possible values: `live`, `test`
- `tag` (array): 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.
- `iccid_prefix` (string): 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.
- `display_name` (string): 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.
- `phone_number` (string): 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 body

- `data` (array of object, required): eSIMs, newest first, in compact form; fetch one by id for the full aggregate.
- `data.subscriber_id` (nullable string, required): The assigned service user, or null when the eSIM has no person assignment.
- `data.id` (string, required)
- `data.status` (string, required)
- `data.mode` (string, required)
- `data.iccid` (nullable string, required): ICCID of the eSIM profile, or null while none is allocated.
- `data.phone_number` (nullable string, required): Phone number attached to this eSIM, in E.164 format, as the supplier reports it. Null while none is on record.
- `data.display_name` (nullable string, required): Free-text label for your own reference.
- `data.created_at` (string, required)
- `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

- [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)