Skip to Content
OpenRoam Docs
eSIMs

List eSIM usage history

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

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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

iccid*string

The eSIM's ICCID, from the order item's fulfillment.result.details.iccid.

Query Parameters

page?integer

Page number, from 1; default 1.

Formatint32
Default1
limit?integer

Page size, 1 to 100; default 10.

Formatint32
Default10
from?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.

Formatdate-time
to?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.

Formatdate-time

Response Body

OK

  1. response

A page of an eSIM's usage readings, newest first.

items*array<>
pagination*

Paging of a list response.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/esims/8944501234567890123/usage/history?page=1&limit=10&from=2026-10-01T00%3A00%3A00Z&to=2026-10-31T23%3A59%3A59Z'
Example Response
{  "items": [    {      "iccid": "string",      "esimStatus": "new",      "capturedAt": "2019-08-24T14:15:22Z",      "start": "2019-08-24T14:15:22Z",      "end": "2019-08-24T14:15:22Z",      "usageBand": "none",      "expiryBand": "none",      "allowedData": 0,      "remainingData": 0,      "isDataUnlimited": true,      "allowedSms": 0,      "remainingSms": 0,      "isSmsUnlimited": true,      "allowedVoice": 0,      "remainingVoice": 0,      "isVoiceUnlimited": true    }  ],  "pagination": {    "currentCount": 0,    "totalCount": 0,    "skip": 0,    "limit": 0,    "hasMore": true,    "page": 0,    "totalPages": 0  }}