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 access token (prefix sk.) with the balance:read scope. Data access 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.
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 |