webclaw

Usage and balance

Read your credit balance, plan limits and current billing period. Both paths return the same response; use whichever name reads better in your code. Checking your balance costs no credits.

GET/v1/usage

Current billing period usage and remaining credits.

GET/v1/balance

Same endpoint as /v1/usage, with the identical response.

Response

json
{
  "tier": "growth",
  "credits_used": 1250,
  "credits_limit": 25000,
  "credits_remaining": 24250,
  "bonus_credits": 500,
  "purchased_credits": 500,
  "billing_policy": "v2",
  "effective_credits_limit": 25500,
  "max_sources_per_research": 20,
  "research_used": 3,
  "research_limit": 10,
  "bonus_research": 0,
  "period_start": "2026-11-04T09:12:44.318265Z",
  "period_end": "2026-12-04T09:12:44.318265Z"
}
FieldTypeDescription
tierstringYour plan, such as free, starter, growth, pro, scale or dedicated.
credits_usednumberCredits used in the current billing period.
credits_limitnumberCredits included with your plan for the period.
bonus_creditsnumberExtra credits added to this period, including purchased credit packs.
purchased_creditsnumberPurchased credits added to this period, including any carried over. Spending does not lower this number: the purchased credits you still have are the smaller of purchased_credits and credits_remaining, and that amount carries over to the next period.
effective_credits_limitnumbercredits_limit plus bonus_credits: the total you can use this period.
credits_remainingnumbereffective_credits_limit minus credits_used, never below 0. Check this before a job.
billing_policystringThe pricing catalogue your plan belongs to.
max_sources_per_researchnumberMaximum sources one research run can read.
research_usednumberResearch runs used this period.
research_limitnumberResearch runs included with your plan for the period.
bonus_researchnumberExtra research runs added to this period.
period_startstringStart of the current billing period, RFC 3339 timestamp in UTC.
period_endstringEnd of the current billing period, RFC 3339 timestamp in UTC.
Note
Use an API key without scope restrictions. A key limited to specific endpoints cannot read usage. The endpoint answers even when your subscription is inactive, so you can always see where you stand.

Example: check balance before a batch

One credit covers one page, so compare credits_remaining with the number of URLs before you start a batch.

curl
URLS='["https://example.com/a", "https://example.com/b", "https://example.com/c"]'

REMAINING=$(curl -s https://api.webclaw.io/v1/balance \
  -H "Authorization: Bearer wc_your_api_key" | jq '.credits_remaining')
NEEDED=$(echo "$URLS" | jq 'length')

if [ "$REMAINING" -lt "$NEEDED" ]; then
  echo "Need $NEEDED credits, $REMAINING left" >&2
  exit 1
fi

curl -X POST https://api.webclaw.io/v1/batch \
  -H "Authorization: Bearer wc_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"urls\": $URLS, \"formats\": [\"markdown\"]}"

Get started

Ready to build? Start extracting.

Cancel anytime. One key for every format and endpoint.

View on GitHub