Check eSIM data usage
check-esim-usageRead-onlyIdempotent
How much data an eSIM has used and how much is left, for one eSIM on a paid order. Identified by the order id and the email that bought it, plus the ICCID from get-order-status or get-esim-activation. Allowances are in megabytes. Readings are served from a cache refreshed every couple of minutes: checked_at says when the reading was taken. An unlimited plan reports its full-speed allowance for the current period rather than a total.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"order_id": "<order_id>",
"email": "<email>",
"iccid": "<iccid>"
},
"name": "check-esim-usage"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The email address the order was bought with. | ||
| iccid | Yes | The ICCID of the eSIM to read, as returned by get-order-status. | |
| order_id | Yes | The order id from the buyer's confirmation email or order page. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| iccid | Yes | The eSIM this reading belongs to. | |
| status | Yes | eSIM state at the time of the reading, e.g. "active". | |
| checked_at | Yes | When this reading was TAKEN, ISO 8601. Readings come from a cache refreshed every couple of minutes, so do not present the number as live. | |
| expires_at | Yes | When the plan lapses, ISO 8601. Null when the supplier reports none. | |
| activated_at | Yes | When the eSIM first connected, ISO 8601. Null before activation. | |
| data_used_mb | Yes | Megabytes used on the current bundle; 1 GB is 1024 MB. | |
| is_unlimited | Yes | Whether the plan is sold as unlimited. Almost none are uncapped: see the period fields for what that actually means here. | |
| period_reset | Yes | How often it refills: "daily", "weekly" or "monthly". Null when it does not. | |
| data_total_mb | Yes | Size of the current bundle in megabytes, reflecting any top-ups. Null on an unmetered plan. | |
| percentage_used | Yes | Share of the bundle spent, 0-100. Null on an unmetered plan, where there is no total to be a share of. | |
| data_remaining_mb | Yes | Megabytes left. NULL on an unmetered plan, which does not mean zero: it means the supplier reports no allowance to count down. | |
| period_remaining_mb | Yes | Full-speed data left in the CURRENT reset period, for a plan whose allowance refills (say 3 GB a day). Null when the plan has no reset period. Deliberately separate from data_remaining_mb, which describes the whole plan. | |
| percentage_remaining | Yes | Share of the bundle left, 0-100. Null on the same terms. | |
| period_high_speed_mb | Yes | Size of that period allowance, so the figure above can be read as "945 MB of 3 GB left today". | |
| period_reduced_speed_kbps | Yes | Speed the plan throttles to once the period allowance is spent. NULL means the data STOPS instead, which is a different thing to tell a traveller. |