# List eSIM usage history (/docs/api-reference/esims/get-usage-history)

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

Lists the recorded usage readings of an eSIM, newest first.

Returns `{ items, pagination }`, one item per usage reading, with its allowances, remaining amounts and
usage and expiry bands. `from` and `to` limit the readings by `capturedAt`, both inclusive. An
ICCID that is not one of your eSIMs gives 404 / 10004.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
| `page` | query | no | `integer` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
| `from` | query | no | `string` | Only readings captured at or after this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `to` | query | no | `string` | Only readings captured at or before this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |

## Responses

### 200

OK

- `text/plain`: `EsimUsageReadingList`
- `application/json`: `EsimUsageReadingList`
- `text/json`: `EsimUsageReadingList`

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 401

Unauthorized

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 404

Not Found

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 429

Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.

- `application/json`: `ErrorResponse`

The full schemas are in the OpenAPI specification at /openapi.json.