Get the usage of an eSIM
Get the remaining and the total data, voice and SMS of one eSIM of your agency, with its status and expiry.
/api/v1/esims/usage/{iccid}Usage is not real time. The last answer is kept for 15 minutes per eSIM (cached and cache_age_seconds), and force=true asks the supplier again. Use force after a topup or when a traveler is waiting, not to poll: the supplier limits how often usage can be read. If the supplier cannot answer, the last known usage is returned with stale: true and a stale_reason; without a last known value the call fails with the supplier's status, and retry_after says how long to wait when the supplier was rate limited.
remaining and total are in megabytes. In the sandbox the usage of a new eSIM is the full allowance and does not change after a topup.
curl https://api.fx-port.com/api/v1/esims/usage/8900000540463077957 \
-H "Authorization: Bearer fxp_test_YOUR_KEY"{
"environment": "sandbox",
"success": true,
"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"
}
}
}{
"environment": "sandbox",
"success": true,
"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"
}
},
"cached": true,
"cache_age_seconds": 0
}Request
Path parameters
iccidstringrequiredThe eSIM to read. It must be an eSIM that your agency ordered.
Query parameters
forcebooleanSkip the 15-minute cache and ask the supplier again. An empty value means not sent.
Default false.
Response
200The usage of the eSIM.
successbooleantrue when usage is returned.
dataobjectThe usage and the supplier's status line.
ShowHide 2 attributes
dataobjectThe usage of one eSIM.
ShowHide 9 attributes
remainingintegerData left, in megabytes.
totalintegerData allowance of the eSIM, in megabytes.
expired_atstringWhen the eSIM expires: YYYY-MM-DD HH:MM:SS, UTC, without a zone.
is_unlimitedbooleantrue for an unlimited eSIM.
statusstringState of the eSIM, as the supplier reports it. One of ACTIVE, EXPIRED, NOT_ACTIVE, FINISHED.
remaining_voiceintegerVoice minutes left.
remaining_textintegerSMS left.
total_voiceintegerVoice minutes of the allowance.
total_textintegerSMS of the allowance.
metaobjectThe supplier's status line.
ShowHide 1 attribute
messagestringsuccess when the supplier answered.
cachedbooleantrue when the usage comes from the 15-minute cache or is a last known value. Absent on a fresh answer.
cache_age_secondsintegerAge of the cached usage in seconds. Present with cached when the value is within the cache window.
stalebooleantrue when the supplier could not answer and the last known usage is returned instead.
stale_reasonstringWhy the supplier could not answer. Present with stale.
retry_afterintegerSeconds to wait before asking the supplier again. Present with stale when the supplier was rate limited.
Errors
| Status | Code | Example message |
|---|---|---|
| 400 | invalid_iccid | iccid must be 18-22 digits (received '123'). |
| 404 | iccid_not_found | No eSIM with this ICCID was found for your account. |
| 429 | rate_limit_exceeded | Rate limited |
The shape of the error body depends on the endpoint. See Errors for every shape and code.