Get the usage of several eSIMs
Get the usage of several eSIMs of your agency in one call.
/api/v1/esims/usage/bulkAlways send iccids (comma separated, at most 50 for an API key). Without it the call reads the 50 newest eSIM orders of your agency in this environment and the supplier is asked one eSIM after another, which can take several seconds. ICCIDs that are not yours are left out of the answer, and each ICCID appears once.
Each entry has its own status: read it per entry. The same 15-minute cache, force and stale values as the single call apply per eSIM. An order whose eSIM the supplier has not returned yet has an ICCID that starts with PENDING- and the status PENDING.
curl 'https://api.fx-port.com/api/v1/esims/usage/bulk?iccids=8900000540463077957' \
-H "Authorization: Bearer fxp_test_YOUR_KEY"{
"environment": "sandbox",
"success": true,
"data": [
{
"iccid": "8900000540463077957",
"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"
}
},
"status": "success"
}
]
}Request
Query parameters
iccidsstringICCIDs separated by commas (semicolons and line breaks work too), at most 50 for an API key. The parameter may also be repeated (iccids=a&iccids=b) or written iccids[]=a&iccids[]=b, and an ICCID may be written in groups of spaces or hyphens. Without it the 50 newest eSIM orders of your agency are read.
forcebooleanSkip the 15-minute cache for every eSIM and ask the supplier again. An empty value means not sent.
Default false.
Response
200One entry per ICCID.
successbooleantrue when the list was built, even if single entries failed: read status per entry.
dataarray of objectOne entry per eSIM of your agency.
ShowHide 5 attributes
iccidstringThe ICCID. Each ICCID appears once.
dataobjectnullableThe 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.
statusstringsuccess fresh or cached, stale last known value, rate_limited the supplier refused (see retry_after), error (see error), or PENDING when the order has no eSIM yet (data is null).
One of success, stale, rate_limited, error, PENDING.
retry_afterintegerSeconds to wait before asking again. Present when status is rate_limited.
errorstringA short reason code. Present when status is error after an unexpected failure.
Errors
| Status | Code | Example message |
|---|---|---|
| 400 | invalid_iccid | iccids must be 18-22 digits (received '123'). |
| 400 | too_many_iccids | iccids accepts at most 50 ICCIDs per request. |
The shape of the error body depends on the endpoint. See Errors for every shape and code.