# Get the usage of an eSIM

> Get the remaining and the total data, voice and SMS of one eSIM of your agency, with its status and expiry.

Endpoint: `GET /esims/usage/{iccid}`

Source: https://fx-port.com/docs/api/get-esim-usage

`GET /api/v1/esims/usage/{iccid}`

Requires an API key with **Read** permission; a **Read+Write** key works too.

Usage is not real time. The last answer is kept for 15 minutes per eSIM (`cached` and `cache_age_seconds`), and `force=true` asks the supplier again. Use `force` after a topup or when a traveler is waiting, not to poll: the supplier limits how often usage can be read. If the supplier cannot answer, the last known usage is returned with `stale: true` and a `stale_reason`; without a last known value the call fails with the supplier's status, and `retry_after` says how long to wait when the supplier was rate limited.

`remaining` and `total` are in megabytes. In the sandbox the usage of a new eSIM is the full allowance and does not change after a topup.

## Request

### Path parameters

- `iccid` (string, required): The eSIM to read. It must be an eSIM that your agency ordered.

### Query parameters

- `force` (boolean, optional): Skip the 15-minute cache and ask the supplier again. An empty value means not sent. Default `false`.

### Example request

```bash
curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
```

## Response

### 200: The usage of the eSIM.

- `success` (boolean): `true` when usage is returned.
- `data` (object): The usage and the supplier's status line.
  - `data` (object): The usage of one eSIM.
    - `remaining` (integer): Data left, in megabytes.
    - `total` (integer): Data allowance of the eSIM, in megabytes.
    - `expired_at` (string): When the eSIM expires: `YYYY-MM-DD HH:MM:SS`, UTC, without a zone.
    - `is_unlimited` (boolean): `true` for an unlimited eSIM.
    - `status` (string): State of the eSIM, as the supplier reports it. One of `ACTIVE`, `EXPIRED`, `NOT_ACTIVE`, `FINISHED`.
    - `remaining_voice` (integer): Voice minutes left.
    - `remaining_text` (integer): SMS left.
    - `total_voice` (integer): Voice minutes of the allowance.
    - `total_text` (integer): SMS of the allowance.
  - `meta` (object): The supplier's status line.
    - `message` (string): `success` when the supplier answered.
- `cached` (boolean): `true` when the usage comes from the 15-minute cache or is a last known value. Absent on a fresh answer.
- `cache_age_seconds` (integer): Age of the cached usage in seconds. Present with `cached` when the value is within the cache window.
- `stale` (boolean): `true` when the supplier could not answer and the last known usage is returned instead.
- `stale_reason` (string): Why the supplier could not answer. Present with `stale`.
- `retry_after` (integer): Seconds to wait before asking the supplier again. Present with `stale` when the supplier was rate limited.

```json
{
  "environment": "sandbox",
  "success": true,
  "data": {
    "data": {
      "remaining": 1024,
      "total": 1024,
      "expired_at": "2026-11-08 15:23:29",
      "is_unlimited": false,
      "status": "ACTIVE",
      "remaining_voice": 0,
      "remaining_text": 0,
      "total_voice": 0,
      "total_text": 0
    },
    "meta": {
      "message": "success"
    }
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_iccid` | iccid must be 18-22 digits (received '123'). |
| 404 | `iccid_not_found` | No eSIM with this ICCID was found for your account. |
| 429 | `rate_limit_exceeded` | Rate limited |

See [Errors](https://fx-port.com/docs/errors.md) for every code and how to react.

## Related guides

- [eSIM usage](https://fx-port.com/docs/esims/usage.md)