On this page Overview

Get balance

Read the wallet balance shared by your dashboard and API purchases.

01 / Request

Make a request

GET/api/v1/balance

balanceUsd is the exact available USD balance as a decimal string, including fractional cents from CAPTCHA charges. balanceCents is rounded down to whole cents for existing integrations.

Use the signed-in wallet to top up. This API does not expose wallet top-ups or API-key management.

Required headers

AuthorizationstringRequired: Bearer followed by your ScrapingBuddy customer API key. Keep it on your server.

Authentication guide

Query parameters

This endpoint does not require parameters.

GET /balance

# Set SCRAPINGBUDDY_API_KEY in your server environment.
curl "https://www.scrapingbuddy.com/api/v1/balance" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY"

Node.js 20+

// Node.js 20+. Keep credentials on your server.
const base = "https://www.scrapingbuddy.com/api/v1";
const response = await fetch(base + "/balance", {
  method: "GET",
  headers: {
    Authorization: "Bearer " + process.env.SCRAPINGBUDDY_API_KEY,
  },
  signal: AbortSignal.timeout(30000),
});
const data = await response.json();
if (!response.ok) throw new Error(response.status + ": " + data.error);
console.log(data);

Python 3 + requests

# Python 3. Install: pip install requests
import os
import requests

base = "https://www.scrapingbuddy.com/api/v1"
headers = {"Authorization": "Bearer " + os.environ["SCRAPINGBUDDY_API_KEY"]}
response = requests.get(
    base + "/balance",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)

Base URL https://www.scrapingbuddy.com/api/v1

Set the environment variables shown in the example. Python requires requests; JavaScript requires Node.js 20+. These examples call the live API, not a sandbox.

02 / Response

Understand the response

Success returns HTTP 200 with JSON. Read the fields below before using the result.

balanceCentsinteger: Available balance rounded down to whole USD cents.
balanceUsddecimal string: Exact available USD balance, with up to nine decimal places; excludes active reservations.
currencystring: USD.

Example response / illustrative values

{
  "balanceCents": 1250,
  "balanceUsd": "12.500000000",
  "currency": "USD"
}

Prices, stock, phone numbers, messages and timestamps here are illustrative, not live availability or a price guarantee.

Errors & next steps

Failures return an HTTP error status and a JSON error message. Correct validation and authentication errors before retrying. For 429, honor Retry-After; longer account limits may still apply.

All keys share the account limit of 60 API requests per minute. Purchase recovery must keep the original idempotency key and quote ID.

Errors & limits Safe purchases & retries Order lifecycle