Get eSIM data usage

POST

/esims/usage

const url = 'https://api.roamex.com/v1/esims/usage?lang=nl';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"esimId":"00000000-0000-4000-8000-0000000000c1","refresh":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.roamex.com/v1/esims/usage?lang=nl' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "esimId": "00000000-0000-4000-8000-0000000000c1", "refresh": true }'

Returns an eSIM’s data usage and validity. With refresh: true the figures are first read live from the network and stored; if that read fails, the stored figures are returned. Check lastRefreshedAt for the age of the figures.

Authorizations

apiKey

Parameters

Query Parameters

lang

string

default: en

Language of plan and destination names in the response: en, nl, es, de, it, fr, pl, pt, tr, el, cs or ro. Any other value, or none, gives English. It never changes which items are returned or any figure.

Example

nl

Request Body^required

application/json

object

esimId

required

string format: uuid

refresh

Read current figures from the network first. Ignored until the eSIM is provisioned.

boolean

Example

{
  "esimId": "00000000-0000-4000-8000-0000000000c1",
  "refresh": true
}

Responses

200

The usage.

application/json

object

success

required

boolean

esim

required

object

required

string format: uuid

planName

required

string

status

required

pending: not ready to install yet.
ready: can be installed, including after it was removed from a device.
installed: on a device.
active: in use, and data has been used.
expired: all data is used (statusLabel Used Up). An eSIM past its end date keeps its other status; compare validity.expiresAt.
cancelled: cancelled by you or on the network, or spent and removed from the device.

string

Allowed values: pending ready installed active expired cancelled

usage

required

object

total

required

object

bytes

required

0 when unknown.

integer

formatted

required

Two decimals in GB, whole numbers in MB and KB, 0 B when unknown.

string

used

required

object

bytes

required

0 when unknown.

integer

formatted

required

Two decimals in GB, whole numbers in MB and KB, 0 B when unknown.

string

remaining

required

object

bytes

required

0 when unknown.

integer

formatted

required

Two decimals in GB, whole numbers in MB and KB, 0 B when unknown.

string

percentUsed

required

Rounded. 0 when the total is unknown.

integer

percentRemaining

required

Rounded. 0 when the total is unknown.

integer

validity

required

object

days

required

integer | null

unit

required

string

expiresAt

required

When the validity ends, once known.

string | null

activatedAt

required

When the eSIM was activated, once known.

string | null

lastRefreshedAt

required

When the figures were last read from the network.

string | null

Example

{
  "success": true,
  "esim": {
    "id": "00000000-0000-4000-8000-0000000000c1",
    "planName": "Japan · 1 GB · 7 days",
    "status": "active"
  },
  "usage": {
    "total": {
      "bytes": 1073741824,
      "formatted": "1.00 GB"
    },
    "used": {
      "bytes": 268435456,
      "formatted": "256 MB"
    },
    "remaining": {
      "bytes": 805306368,
      "formatted": "768 MB"
    },
    "percentUsed": 25,
    "percentRemaining": 75
  },
  "validity": {
    "days": 7,
    "unit": "DAY",
    "expiresAt": "2026-10-29T08:00:00Z",
    "activatedAt": "2026-10-22T08:00:00Z"
  },
  "lastRefreshedAt": "2026-10-22T09:00:00.000Z"
}

Headers

X-RateLimit-Limit

integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining

integer

Calls left in the current minute.

X-RateLimit-Reset

integer

When the current window ends, in Unix seconds.

400

INVALID_JSON: the body is missing or not a JSON object.
MISSING_ESIM_ID: esimId is missing.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

401

AUTH_ERROR: the key is missing, malformed, unknown or revoked. The message says which, for example Missing Authorization header, Invalid Authorization header format. Use: Bearer <api_key>, Invalid API key format or Invalid API key.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key"
  }
}

403

AUTH_ERROR: the account is suspended (Your account is suspended. Please contact support.) or rejected (Account is not approved for API access).

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

404

ESIM_NOT_FOUND: no eSIM with this id belongs to your account.
NOT_FOUND: the API is switched off on the platform.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

413

PAYLOAD_TOO_LARGE: the Content-Length header is over 100 KB.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

429

RATE_LIMITED: the account’s per-minute budget for this endpoint group is used up, or too many refused keys came from this IP address. Wait the Retry-After seconds.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please wait 42 seconds before retrying."
  }
}

Headers

X-RateLimit-Limit

integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining

integer

Calls left in the current minute.

X-RateLimit-Reset

integer

When the current window ends, in Unix seconds.

Retry-After

integer

Seconds to wait before retrying.

500

INTERNAL_ERROR: an unexpected error on our side.
AUTH_ERROR with status 500: the key could not be checked because of an error on our side. Retry with backoff.

application/json

object

success

required

boolean

error

required

object

code

required

Machine-readable. Branch on this.

string

message

required

A sentence for people. It can change.

string

Example

{
  "success": false
}

Get eSIM data usage

Authorizations

Parameters

Query Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

Headers

400

Example

401

Example

403

Example

404

Example

413

Example

429

Example

Headers

500

Example

Request Body^required