# Get eSIM

> Returns the status of an eSIM you ordered, its current tier and, once it is ACTIVE , its mobile data use this month. Use it to poll for readiness if you do…

`GET /v2/api/partner/esims/{id}`

<Note>
**Required scope:** `PARTNER`
</Note>

Returns the status of an eSIM you ordered, its tier and its mobile data use this month. The [`partner.esim.ready`](/docs/webhooks/event-catalog#partneresimready) and [`partner.esim.failed`](/docs/webhooks/event-catalog#partneresimfailed) webhooks tell you when the status changes. Without a webhook endpoint, poll this endpoint instead, within the [rate limit](/docs/guides/rate-limits) of 20 read requests per second per key.

| `status` | What it means |
|----------|---------------|
| `PROVISIONING` | The eSIM is ordered and not ready yet. This usually takes 5 to 15 minutes. |
| `ACTIVE` | The eSIM is ready. Calls to the number ring the eSIM. Get the [activation code](/docs/white-label/get-esim-activation-code) to deliver it to your client. |
| `FAILED` | The order did not complete. `failure_code` gives the reason. |
| `REVOKED` | The eSIM was [revoked](/docs/white-label/revoke-esim), or replaced by a later eSIM on the same number. It no longer works on its phone, and calls to the number ring the Allo apps. |

`failure_code` is `null` unless `status` is `FAILED`. You can only read eSIMs ordered on accounts your own API key created. Any other id fails with `PARTNER_ESIM_NOT_FOUND`.

## Tier

- `tier` is the eSIM's current tier. It changes when an upgrade from [Change eSIM tier](/docs/white-label/change-esim-tier) is paid, or when a scheduled downgrade applies. Until then, it is the tier you ordered.
- `scheduled_tier` is the tier a scheduled downgrade will switch the eSIM to, and `scheduled_tier_at` is when, at the end of the period already paid. Both are `null` when no downgrade is scheduled.

## Data use

`data` gives the eSIM's mobile data use for the current month. It is `null` unless `status` is `ACTIVE`.

| Field | What it means |
|-------|---------------|
| `used_mb` | Mobile data used this month, in MB. `null` when the network has not reported it yet. |
| `allowance_mb` | Mobile data the eSIM can use this month, in MB: the tier's data plus the [top-ups](/docs/white-label/buy-esim-topup) bought this month. |
| `remaining_mb` | `allowance_mb` minus `used_mb`, in MB, never below 0. `null` when `used_mb` is `null`. |
| `cycle_started_at` | Start of the current month, in UTC. |
| `cycle_ends_at` | End of the current month, in UTC. The next month starts at this time. |

- The cycle is the calendar month in Paris time. The timestamps are in UTC, so in November 2026 the cycle runs from `2026-10-31T23:00:00` to `2026-11-30T23:00:00`.
- Allo reads the use live from the network on each call. It can lag real use by a few minutes.
- When the eSIM reaches its allowance, mobile data stops until the next month or until you [buy a top-up](/docs/white-label/buy-esim-topup). Calls and SMS keep working. The line is never billed for data beyond the allowance.
- Allo sends [`partner.esim.data_low`](/docs/webhooks/event-catalog#partneresimdata_low) when the eSIM has used 80% of its allowance, and [`partner.esim.data_exhausted`](/docs/webhooks/event-catalog#partneresimdata_exhausted) when it has used all of it. You do not need to poll this endpoint to watch the data.
