Billing summary
Plan, credit balance and when the current period ends.
The first call a new integration should make: it reports whether the key is metered at all, what it has left and what renews when. Free.
Request
https://api.scrapercompany.com/v1/billingAuthenticate with your API key in the x-api-key header (see Authentication).
Run this request on your own API key from this page, with the values you type. Signed out? Sign in or get an API key.
Example request
curl "https://api.scrapercompany.com/v1/billing" \
-H "x-api-key: $SCRAPERCOMPANY_API_KEY"Response
200 — Plan, balance and current period.
{
"mode": "shadow",
"plan": {
"code": "starter",
"name": "Starter",
"monthly_credits": 40000,
"price_usd": 49,
"concurrency": 10
},
"credits": {
"balance": 45710,
"reserved": 20,
"available": 45690,
"topup": 7500,
"allowance_left": 38210,
"credits_used": 1790,
"credits_refunded": 0,
"billable_requests": 312,
"credits_adjusted": 0,
"filled_balance": 47500
},
"period": {
"start": "2026-10-01T00:00:00+00:00",
"end": "2026-11-01T00:00:00+00:00"
},
"subscription": {
"status": "active",
"stripe_managed": true,
"cancel_at_period_end": true,
"cancels_at": "2026-11-01T00:00:00+00:00"
}
}Response fields
Fields marked required are always present; others appear when they apply.
- modestringrequired
Credit metering mode.
enforce: a request that needs more credits than are available gets 402, and the plan's concurrent-request limit applies (429).shadow: every request is metered and recorded but never blocked.off: not metered.One of
offshadowenforce - planobjectrequired
Show 5 child fieldsHide child fields
- plan.codestringrequired
Plan code.
One of
freestartergrowthscaleenterprise - plan.namestringrequired
- plan.monthly_creditsintegerrequired
Credits granted at the start of each period.
- plan.price_usdintegerrequired
Monthly price in USD; 0 = free, -1 = custom (sales).
- plan.concurrencyintegerrequired
Concurrent metered requests allowed; applied in
enforcemode.
- creditsobjectrequired
Show 6 child fieldsHide child fields
- credits.balanceintegerrequired
Credits on the account. In
enforcemode requests are refused before it would go below zero; inshadowmode it can go negative and the overdraft is forgiven at renewal. - credits.reservedintegerrequired
Credits held by requests that are still running.
- credits.availableintegerrequired
balance - reserved. - credits.credits_usedintegerrequired
Credits charged this period.
- credits.credits_refundedintegerrequired
Credits returned this period.
- credits.billable_requestsintegerrequired
Requests charged this period.
- periodobjectrequired
Show 2 child fieldsHide child fields
- period.startstring (date-time)required
- period.endstring (date-time)required
Renewal time; unspent credits expire then.
- subscriptionobject
Show 2 child fieldsHide child fields
- subscription.statusstring
- subscription.stripe_managedboolean
Errors
Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.
| Status | Meaning | Retry? |
|---|---|---|
401Unauthorized | Missing or invalid API key. {"detail":"missing or invalid API key"} | No, fix the request |
404Not Found | The property, stay, job or record was not found. {"detail":"job not found"} | No, fix the request |
429Too Many Requests | Too many requests: the key's requests-per-minute limit was exceeded, or (in {"detail":"rate limit 60/min exceeded"} | Yes, with backoff |
Try it
Press Try it above to run this request on your own key, with the values you type (sign in first). For a no-code walkthrough, use the workspace’s guided Try it.
- Export your key:
export SCRAPERCOMPANY_API_KEY=sk_...(no key yet? start a free trial). - Copy the cURL example above and run it in a terminal.
Questions about this page?
Send the page link and your question, and the team will answer.