API keys & rate limits

Every request is authenticated with an API key and counted against your account's requests per second.

Sending the key

Put the key in the X-API-Key header of every request. Keys in the URL are refused, so they never end up in proxy or browser logs. Create, rename and revoke keys on the API keys page of the dashboard.

BASH

curl https://api.serpbase.dev/account/credits \
  -H "X-API-Key: YOUR_API_KEY"

Rate limits

A request over your limit is refused at once with status 1029 and a Retry-After header, and is not charged. X-RateLimit-Limit and X-RateLimit-Remaining on every response let your client pace itself.

Automatic account QPS upgrades

After an eligible top-up is confirmed as credited, cumulative USD thresholds raise account QPS to at least: $3 → 2, $50 → 5, $100 → 10, $200 → 15, $1,000 → 50, $10,000 → 500. Below $3, your current account limit is unchanged. Upgrades only raise the limit; they never lower an existing higher limit. This is not unlimited QPS.

Cumulative eligible top-ups (USD)	Upgrade to at least (QPS)
≥ $3	2 QPS
≥ $50	5 QPS
≥ $100	10 QPS
≥ $200	15 QPS
≥ $1,000	50 QPS
≥ $10,000	500 QPS

Only USD credit-pack (credit_pack) and automatic top-up (auto_topup) payments confirmed as credited count. Subscriptions (including Starter Boost), gifts and gift codes do not count. Credit balances are not cumulative USD payments. Non-USD payments are not counted as USD without currency conversion.

All API keys, products and gateways for the same account share one QPS limit. Creating more keys does not increase it.

Eligible top-ups automatically raise account QPS after confirmed crediting, not merely after returning from checkout. The current limit is the server-reported value shown in your account; API key synchronization may briefly lag.

Account balance

Retrieve the current credit balance for the account that owns an active API key. This request does not consume search credits.

GET

0 credits

/account/credits

Pass the key in the X-API-Key header. API keys in URL query parameters are not accepted.

BASH

curl https://api.serpbase.dev/account/credits \
  -H "X-API-Key: your_api_key"

JSON

{
  "status": 0,
  "credits": 12345,
  "permanent_credits": 10000,
  "expiring_credits": 2345,
  "expiring_expires_at": 1798761600
}

The endpoint is limited to 60 requests per minute per account. expiring_expires_at is a Unix timestamp in seconds and is 0 when no limited-time credits are active.