eSIM usage
Retrieve remaining data, voice, and SMS balance for one or all eSIMs.
Usage is cached and is not real-time. FX-Port caches usage responses for up to 15 minutes
per ICCID to protect the supplier's rate limits. Pass force=true to bypass the cache and query
the supplier directly when you need the freshest possible number (for example right after a
topup) — but avoid doing this on every request, since suppliers rate-limit usage lookups
themselves and can temporarily reject requests that poll too frequently.
Single eSIM usage
GET /api/v1/esims/usage/{iccid}
Permission: Read
curl --request GET \
--url 'https://api.fx-port.com/api/v1/esims/usage/8900000338153738419?force=false' \
--header 'Authorization: Bearer fxp_test_YOUR_KEY'| Query parameter | Description |
|---|---|
force | Bypass the cache and re-query the supplier for the latest usage |
Response example
{
"success": true,
"data": {
"data": {
"remaining": 1024,
"total": 1024,
"expired_at": "2026-09-03 12:56:28",
"is_unlimited": false,
"status": "ACTIVE",
"remaining_voice": 0,
"remaining_text": 0,
"total_voice": 0,
"total_text": 0
},
"meta": { "message": "success" }
}
}remaining and total are in megabytes. status is one of ACTIVE, EXPIRED, NOT_ACTIVE,
or FINISHED depending on the supplier.
Bulk usage
GET /api/v1/esims/usage/bulk
Permission: Read
Returns usage for every eSIM owned by the authenticated agency in one call — useful for dashboards
that show all active eSIMs at once. This endpoint is also subject to the same 15-minute cache and
force bypass described above, applied per ICCID.
curl --request GET \
--url 'https://api.fx-port.com/api/v1/esims/usage/bulk?force=false' \
--header 'Authorization: Bearer fxp_test_YOUR_KEY'{
"success": true,
"data": [
{
"iccid": "8900000847275756911",
"data": {
"data": {
"remaining": 0,
"total": 0,
"expired_at": "2026-05-16 09:39:02",
"is_unlimited": false,
"status": "EXPIRED",
"remaining_voice": 0,
"remaining_text": 0,
"total_voice": 0,
"total_text": 0
},
"meta": { "message": "success" }
},
"status": "success"
}
]
}status per entry is success, rate_limited, or error — retry rate_limited entries later
rather than immediately re-calling bulk usage.