# Get the usage of several eSIMs

> Get the usage of several eSIMs of your agency in one call.

Endpoint: `GET /esims/usage/bulk`

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

`GET /api/v1/esims/usage/bulk`

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

Always send `iccids` (comma separated, at most 50 for an API key). Without it the call reads the 50 newest eSIM orders of your agency in this environment and the supplier is asked one eSIM after another, which can take several seconds. ICCIDs that are not yours are left out of the answer, and each ICCID appears once.

Each entry has its own `status`: read it per entry. The same 15-minute cache, `force` and stale values as the single call apply per eSIM. An order whose eSIM the supplier has not returned yet has an ICCID that starts with `PENDING-` and the status `PENDING`.

## Request

### Query parameters

- `iccids` (string, optional): ICCIDs separated by commas (semicolons and line breaks work too), at most 50 for an API key. The parameter may also be repeated (`iccids=a&iccids=b`) or written `iccids[]=a&iccids[]=b`, and an ICCID may be written in groups of spaces or hyphens. Without it the 50 newest eSIM orders of your agency are read.
- `force` (boolean, optional): Skip the 15-minute cache for every eSIM 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/bulk?iccids=8900000540463077957' \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
```

## Response

### 200: One entry per ICCID.

- `success` (boolean): `true` when the list was built, even if single entries failed: read `status` per entry.
- `data` (array of object): One entry per eSIM of your agency.
  - `iccid` (string): The ICCID. Each ICCID appears once.
  - `data` (object, nullable): 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.
  - `status` (string): `success` fresh or cached, `stale` last known value, `rate_limited` the supplier refused (see `retry_after`), `error` (see `error`), or `PENDING` when the order has no eSIM yet (`data` is null). One of `success`, `stale`, `rate_limited`, `error`, `PENDING`.
  - `retry_after` (integer): Seconds to wait before asking again. Present when `status` is `rate_limited`.
  - `error` (string): A short reason code. Present when `status` is `error` after an unexpected failure.

```json
{
  "environment": "sandbox",
  "success": true,
  "data": [
    {
      "iccid": "8900000540463077957",
      "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"
        }
      },
      "status": "success"
    }
  ]
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_iccid` | iccids must be 18-22 digits (received '123'). |
| 400 | `too_many_iccids` | iccids accepts at most 50 ICCIDs per request. |

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)