---
title: "List eSIMs"
method: GET
path: "/v1/esim/sims"
tags: ["esims"]
---

# List eSIMs

`GET /v1/esim/sims`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/esim/sims`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Returns your workspace's eSIMs as a cursor-paginated list, newest first.
Filter by lifecycle `status`, recurring subscription (`renewal`), 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.

## Query parameters

- `limit` integer
- `starting_after` string
- `ending_before` string
- `subscriber_id` string
- `created_after` string, date-time
- `created_before` string, date-time
- `status` EsimStatus[]
- `iccid` string
- `mode` 'live' | 'test': Whether a purchase or eSIM is live or simulated. The mode is fixed when the order is created; the resulting eSIM retains it. - `live`: purchases service for use on a device and charges the wallet. - `test`: simulates a purchase without a charge or usable mobile service. List responses can include both modes. Filter by `mode` when separating test activity from live purchases.
- `renewal` EsimRenewalState[]
- `tag` string[]
- `iccid_prefix` string
- `display_name` string
- `phone_number` string

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

Paginated list of eSIMs.

- EsimList
  - `data` EsimSummary[], required: eSIMs, newest first, in compact form; fetch one by id for the full aggregate.
    - `subscriber_id` string, required
    - `id` string, required
    - `status` 'provisioning' | 'ready' | 'activating' | 'active' | 'suspending' | 'suspended' | 'resuming' | 'releasing' | 'released' | 'expired' | 'failed', required: Lifecycle state of an eSIM. A pending state always settles: to its target on success, or back to the prior status when the network definitively rejects the change, reported by the `esim.operation_failed` event. - `provisioning`: the initial data package is being applied; install credentials may already be available. - `ready`: installable and usable, waiting for first network use; allows top-up orders and release. Activate before `ready_until` or the eSIM expires. - `activating`: an activation is being applied. - `active`: in service; the service period ends at `active_until`. Allows top-up orders, suspend, resync, and release. - `suspending`: a suspension was requested and is being applied. - `suspended`: data service is paused; allows resume and release. - `resuming`: a resume was requested and is being applied. - `releasing`: a permanent release is in progress. - `released`: permanently released; terminal. - `expired`: dormant. No data package has been live (each one depleted, expired, removed, or failed) for the expiry window. Not terminal: a completed top-up returns the eSIM to `active`, and release remains available. Balances and the installed profile are untouched. - `failed`: provisioning failed; any charge on the owning order is credited back automatically, reported by that order. Terminal.
    - `mode` 'live' | 'test', required: Whether a purchase or eSIM is live or simulated. The mode is fixed when the order is created; the resulting eSIM retains it. - `live`: purchases service for use on a device and charges the wallet. - `test`: simulates a purchase without a charge or usable mobile service. List responses can include both modes. Filter by `mode` when separating test activity from live purchases.
    - `iccid` string, nullable, required: ICCID of the eSIM profile, or null while none is allocated.
    - `phone_number` string, nullable, required: Phone number attached to this eSIM, in E.164 format, as the supplier reports it. Null while none is on record.
    - `display_name` string, nullable, required: Free-text label for your own reference.
    - `renewal` EsimRecurringSubscriptionSummary, required: The eSIM's recurring subscription that has not ended. Fetch the subscription by id for its price, cadence, next charge and period history.
      - `subscription_id` string, required
      - `status` 'pending' | 'active' | 'needs_attention' | 'ended', required: Delivery state of the recurring service. Check payment and renewal fields separately. - `pending`: enrollment or the initial purchase is still being processed. - `active`: the service has delivered a package and remains active. - `needs_attention`: delivery or a related credit remains unresolved. Check period history and the associated order before purchasing a replacement. - `ended`: recurrence has ended. Previously delivered packages keep their own validity.
    - `created_at` string, date-time, required
  - `next_cursor` string, nullable, required: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
  - `prev_cursor` string, nullable, required: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
  - `refresh_cursor` string, nullable, 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`.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)