Get remaining usage

GET/v1/esims/{iccid}/usageesims:read

Returns the usage counters for one eSIM: total, used and remaining data, as reported by the network.

This endpoint exists next to Get an eSIM for one reason: that endpoint answers from our records, which the background sync refreshes every few hours. This one refreshes from the provider at request time whenever the stored reading is older than 15 minutes — it is the endpoint to call when your customer asks “how much do I have left”.

Path parameters

Name	Notes
iccid	The ICCID of the eSIM

curl https://partner-api.esimfo.com/v1/esims/89852350326100409575/usage \
  -H 'Authorization: Bearer esf_live_at_...'

Response 200

Field	Type	Notes
iccid	string	Echoed back
status	enum	Same values as Get an eSIM
data_total_mb	integer | null	null on unlimited packages
data_used_mb	integer | null	Consumed so far
data_remaining_mb	integer | null	As reported by the network — not derived. null on unlimited packages
expires_at	string | null	ISO 8601 UTC. null until activation starts the clock
last_synced_at	string | null	When these figures were read from the network

{
  "iccid": "89852350326100409575",
  "status": "ACTIVE",
  "data_total_mb": 3072,
  "data_used_mb": 512,
  "data_remaining_mb": 2560,
  "expires_at": "2026-09-21T00:00:00.000Z",
  "last_synced_at": "2026-08-22T09:41:17.204Z"
}

Notes

Check last_synced_at. If the provider is unreachable when you call, the last known reading is returned instead of an error — a stale number beats no number. last_synced_at tells you how stale it is.

All counters are null before the first sync. A freshly provisioned eSIM that has never connected has nothing to report yet. That is not an error state.

Do not poll for depletion. Subscribe to the esim.depleted webhook instead — polling this endpoint in a loop burns your rate limit to learn something the webhook pushes to you.

Unlimited packages have no meaningful counters. data_total_mb and data_remaining_mb are null; render the plan as unlimited rather than dividing by them.

Errors

Status	Code	Cause
404	not_found	No such ICCID, or it belongs to another account
403	insufficient_scope	Key lacks esims:read