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/usageCurrent billing period usage and remaining credits.
GET
/v1/balanceSame 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"
}| Field | Type | Description |
|---|---|---|
tier | string | Your plan, such as free, starter, growth, pro, scale or dedicated. |
credits_used | number | Credits used in the current billing period. |
credits_limit | number | Credits included with your plan for the period. |
bonus_credits | number | Extra credits added to this period, including purchased credit packs. |
purchased_credits | number | Purchased 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_limit | number | credits_limit plus bonus_credits: the total you can use this period. |
credits_remaining | number | effective_credits_limit minus credits_used, never below 0. Check this before a job. |
billing_policy | string | The pricing catalogue your plan belongs to. |
max_sources_per_research | number | Maximum sources one research run can read. |
research_used | number | Research runs used this period. |
research_limit | number | Research runs included with your plan for the period. |
bonus_research | number | Extra research runs added to this period. |
period_start | string | Start of the current billing period, RFC 3339 timestamp in UTC. |
period_end | string | End 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\"]}"