Get live usage
curl --request GET \
--url https://sandbox-api.sakawave.example/v1/esims/{profileId}/usage \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://sandbox-api.sakawave.example/v1/esims/{profileId}/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://sandbox-api.sakawave.example/v1/esims/{profileId}/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"id": "01K2Z3AB4R5S6T7V8WXYZABCDE",
"orderId": "01K2Z3AB4S5T6V7W8XYZABCDEF",
"status": "ready",
"iccid": "8944478000000123456",
"customerId": null,
"package": {
"id": "01K2Z3AB4C5D6E7F8GHJKMNPQR",
"slug": "united-states-5gb-30d-pkgus5gb",
"name": "United States 5GB",
"region": {
"code": "US",
"name": "United States",
"kind": "country",
"flagEmoji": "πΊπΈ"
}
},
"data": {
"totalBytes": "5368709120",
"usedBytes": "0",
"remainingBytes": "5368709120",
"percentUsed": 0,
"display": "0 B of 5 GB"
},
"validity": {
"validFrom": null,
"expiresAt": "2026-09-28T10:30:00.000Z",
"daysRemaining": 30
},
"smdpStatus": "RELEASED",
"createdAt": "2026-08-29T10:30:00.000Z",
"updatedAt": "2026-08-29T10:30:12.000Z"
}{
"statusCode": 400,
"message": "Must be a valid identifier.",
"code": "validation_failed",
"errors": [
{
"message": "Must be a valid identifier.",
"field": "accountId",
"code": "custom",
"path": [
"accountId"
]
}
]
}{
"statusCode": 401,
"code": "INVALID_API_KEY",
"message": "Invalid or inactive API credentials."
}{
"statusCode": 404,
"code": "resource_not_found",
"message": "Resource not found."
}{
"statusCode": 429,
"message": "Too many API requests. Try again later.",
"code": "api_key_rate_limit_exceeded",
"retryAfterSeconds": 17
}{
"statusCode": 500,
"code": "internal_server_error",
"message": "An unexpected error occurred."
}eSIM
Get live usage
Data used and validity remaining, refreshed from the network when the stored figure is stale.
GET
/
v1
/
esims
/
{profileId}
/
usage
Get live usage
curl --request GET \
--url https://sandbox-api.sakawave.example/v1/esims/{profileId}/usage \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://sandbox-api.sakawave.example/v1/esims/{profileId}/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://sandbox-api.sakawave.example/v1/esims/{profileId}/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"id": "01K2Z3AB4R5S6T7V8WXYZABCDE",
"orderId": "01K2Z3AB4S5T6V7W8XYZABCDEF",
"status": "ready",
"iccid": "8944478000000123456",
"customerId": null,
"package": {
"id": "01K2Z3AB4C5D6E7F8GHJKMNPQR",
"slug": "united-states-5gb-30d-pkgus5gb",
"name": "United States 5GB",
"region": {
"code": "US",
"name": "United States",
"kind": "country",
"flagEmoji": "πΊπΈ"
}
},
"data": {
"totalBytes": "5368709120",
"usedBytes": "0",
"remainingBytes": "5368709120",
"percentUsed": 0,
"display": "0 B of 5 GB"
},
"validity": {
"validFrom": null,
"expiresAt": "2026-09-28T10:30:00.000Z",
"daysRemaining": 30
},
"smdpStatus": "RELEASED",
"createdAt": "2026-08-29T10:30:00.000Z",
"updatedAt": "2026-08-29T10:30:12.000Z"
}{
"statusCode": 400,
"message": "Must be a valid identifier.",
"code": "validation_failed",
"errors": [
{
"message": "Must be a valid identifier.",
"field": "accountId",
"code": "custom",
"path": [
"accountId"
]
}
]
}{
"statusCode": 401,
"code": "INVALID_API_KEY",
"message": "Invalid or inactive API credentials."
}{
"statusCode": 404,
"code": "resource_not_found",
"message": "Resource not found."
}{
"statusCode": 429,
"message": "Too many API requests. Try again later.",
"code": "api_key_rate_limit_exceeded",
"retryAfterSeconds": 17
}{
"statusCode": 500,
"code": "internal_server_error",
"message": "An unexpected error occurred."
}Prefer this over the list when showing one eSIM to the person using it. A network that cannot be reached degrades to the stored figure rather than failing the read.
Usage is also pushed as
esim.usage.low and esim.expiry.near, so you need not poll to warn someone.
Error codes
| Status | code | Cause |
|---|---|---|
404 | esim_profile_not_found | No such eSIM for this business. |
401 | INVALID_API_KEY | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. |
429 | api_key_rate_limit_exceeded | The per-minute limit for this key was exceeded. |
503 | esim_feature_disabled | eSIM is not enabled on this deployment. |
503 | esim_catalog_unavailable | The catalog is empty and could not be refreshed from the provider. |
503 | esim_provider_unavailable | The eSIM provider could not be reached. Nothing was charged. |
Authorizations
A secret API key, sent as Authorization: Bearer sk_test_β¦ in sandbox or Bearer sk_live_β¦ in live.
Path Parameters
eSIM ULID. A 26-character ULID.
Required string length:
26Pattern:
^[0-7][0-9A-HJKMNP-TV-Z]{25}$Example:
"01K2Z3AB4C5D6E7F8G9HJKMNPQ"
Response
Successful response.
A 26-character ULID.
Required string length:
26Pattern:
^[0-7][0-9A-HJKMNP-TV-Z]{25}$Example:
"01K2Z3AB4C5D6E7F8G9HJKMNPQ"
A 26-character ULID.
Required string length:
26Pattern:
^[0-7][0-9A-HJKMNP-TV-Z]{25}$Example:
"01K2Z3AB4C5D6E7F8G9HJKMNPQ"
ready means installable; in_use means the traveller has installed it.
Available options:
pending, ready, in_use, depleted, expired, suspended, revoked, cancelled The SIM identifier, once the network has allocated one.
A 26-character ULID.
Required string length:
26Pattern:
^[0-7][0-9A-HJKMNP-TV-Z]{25}$Example:
"01K2Z3AB4C5D6E7F8G9HJKMNPQ"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Example:
"2026-08-14T09:00:00.000Z"
Example:
"2026-08-14T09:00:00.000Z"