Balance
Check the count of request credits left in your account for the day, and available device slots for device plans.
The Balance API provides a count of request credits left in the user's account for the day. Balance is reset at midnight UTC everyday (00:00 UTC).
For device accounts, this endpoint also returns the number of available device slots.
The Balance API requires an account token (prefix sk.) with the balance:read scope. API tokens (pk.) and legacy parent keys cannot call it and receive HTTP 403 with ACCESS_RESTRICTED. Create the token on your User Dashboard with the Read Balance permission selected - see Access Token Scopes.
From 19th October 2026 (UTC), this endpoint will require an account token with the balance:read scope enabled to continue working. Please update your integrations before this date.
Due to the distributed nature of our API stack that spans multiple continents and datacenters, the values returned by this endpoint will be a few seconds old.
Usage
GET requests can be sent to the following URL. To prevent abuse, this endpoint is rate limited at 1 request per second.
https://us1.unwiredlabs.com/v2/balance?token=YOUR_API_TOKEN
Replace us1 with a region that's closer to your location.
curl --request GET \
--url 'https://us1.unwiredlabs.com/v2/balance?token=YOUR_API_TOKEN'Query Parameters
| Name | Description | Required |
|---|---|---|
| token | Authentication Token | Yes |
Response
The above command returns JSON structured like this:
{
"status": "ok",
"balance_geolocation": 4500,
"balance_geocoding": 4500,
"balance_slots": -1
}| Name | Description |
|---|---|
| status | ok on success; error on error |
| balance_geolocation | Remaining balance left in the account for geolocation requests |
| balance_geocoding | Remaining balance left in the account for geocoding requests |
| balance_slots | Remaining device slots available. Returns -1 if no slots are allocated. This field is only present for device accounts. |
Errors
This API currently always responds with an HTTP 200 status code, even for errors - always check the status field in the response body. The exception is a missing scope, which returns HTTP 403 with ACCESS_RESTRICTED.
{
"status": "error",
"message": "Error message"
}When certain types of errors are encountered, our API responds with the following error messages:
| Error Message | Description |
|---|---|
INVALID_TOKEN | The user's token set is not valid |
ACCESS_RESTRICTED | The access token does not have the balance:read scope required by this endpoint. Returned with HTTP 403. |
INACTIVE_TOKEN | The user's token is not active |
UNKNOWN_ERROR | Due to an unknown error, we are unable to serve your request |
RATELIMITED_SECOND | The user has exceeded the 1 request per-second limit for this endpoint |