---
title: "List an eSIM's data packages"
canonical: "https://bird.com/docs/api/reference/list-esim-packages"
---

# List an eSIM's data packages

`GET /v1/esim/sims/{esim_id}/packages`

Returns the eSIM's data packages with per-zone balances, validity, and status, newest first and in full: an eSIM holds at most package_limit concurrent packages. Balances update as mobile networks report usage; `balance.as_of` tells you how fresh they are.

## Code samples

**CLI**

```sh
bird esim packages list <esim-id>
```

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

## Example response `200`

```json
{
  "data": [
    {
      "id": "epk_01krdgeqcxet5s7t44vh8rt9mg",
      "order_id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
      "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
      "zone_id": "ezn_01krdgeqcxet5s7t44vh8rt9mg",
      "zone_name": "Europe",
      "countries": [
        "US"
      ],
      "status": "provisioning",
      "speed": "full",
      "price": {
        "amount": "0.00995",
        "currency_code": "USD"
      }
    }
  ]
}
```

## Path parameters

- `esim_id` (string): eSIM ID.

## Response body

- `data` (array of object, required): Packages, newest first.
- `data.id` (string, required)
- `data.order_id` (string, required): The order that purchased this package.
- `data.offer_id` (string, required): Offer this package was purchased from.
- `data.zone_id` (string, required): Coverage zone the package draws on. The name and countries below are captured at purchase time; the zone resource carries the live footprint.
- `data.zone_name` (string, required): Coverage zone name, from the offer.
- `data.countries` (array of string, required): Countries the package's zone covers, captured at purchase time so the package is meaningful without fetching the offer.
- `data.status` (string, required)
- `data.speed` (string, required): Speed class, from the offer.
- `data.balance` (object, required)
- `data.balance.total_bytes` (integer, required): Total data in bytes, as purchased. Known from the order, so never null.
- `data.balance.used_bytes` (nullable integer, required): Data used in bytes, or null while no network has reported on this package.
- `data.balance.remaining_bytes` (nullable integer, required): Data remaining in bytes, or null while no network has reported on this package.
- `data.balance.used_percent` (nullable number, required): Share of the total data already used, as a percentage. Null while no network has reported on this package.
- `data.balance.as_of` (string, required): When the balance was last established. Before consumption is reported, this is the package delivery time. Check whether the consumption fields are null before treating this timestamp as a usage update.
- `data.balance.observed_at` (nullable string, required): Measurement time supplied by the mobile network. Null when no measurement or measurement time is available. Use `as_of` for the balance update time.
- `data.activated_at` (nullable string): When the package started consuming data (first use in its zone). Null until then.
- `data.expires_at` (nullable string): When the package's validity ends and unused balance expires. Already capped by the eSIM's service period, so this is always the effective expiry. Null until the package activates.
- `data.price` (object, required): What your workspace was billed for this package.
- `data.price.amount` (string, required): Decimal amount as a string, in major currency units.
- `data.price.currency_code` (string, required): ISO 4217 currency code.
- `data.created_at` (string, required)

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