Usage & Tokens¶

Blaick bills in tokens. This guide explains the token model and the endpoints for checking your balance, usage, and history.

The token model¶

Pricing is deliberately simple:

$1 = 625,000 tokens · 1 US cent = 6,250 tokens

Every chat completion reports its cost in the usage object:

"usage": {
  "input_tokens": 18,
  "output_tokens": 8,
  "total_tokens": 26,
  "cost_tokens": 71
}

input_tokens — tokens in your prompt (messages + system).
output_tokens — tokens the model generated.
total_tokens — input_tokens + output_tokens.
cost_tokens — what you were actually billed. Input and output are priced separately — output costs more, mirroring the underlying providers — so cost_tokens = input_tokens × input rate + output_tokens × output rate. A model's cost_multiplier (see Models) is the blended reference rate.

Raw tokens vs. billed tokens

total_tokens is what the model processed. cost_tokens is what you pay. Higher-tier models bill more per token, and output is weighted more heavily than input. Always use cost_tokens for accounting.

Subscription plans¶

Every plan includes a monthly token grant at the same rate above; unused tokens roll over for up to 3 months (see Token buckets). Prices are billed monthly.

Plan	Price / mo	Included tokens
Starter	$29	18,000,000
Professional	$49	30,000,000
Pro	$89	55,000,000
Enterprise	$149	93,000,000

Fetch the live list any time with GET /billing/plans. Need more? Enable overage or buy a one-time top-up (POST /billing/purchase) at the rate above.

Free trial¶

New accounts get a 14-day free trial with a starting token balance. Trial accounts can only use trial-eligible models (see Models). When the trial ends or tokens run out, requests return 402 until you subscribe or top up. See Errors.

Check your balance¶

Your current balance is on your profile:

curl https://api.blaick.ai/api/v1/users/me \
  -H "Authorization: Bearer $BLAICK_API_KEY"

{
  "id": "…",
  "email": "you@example.com",
  "token_balance": 1000000,
  "is_trial": true,
  "trial_ends_at": "2026-08-18T00:00:00Z"
}

Usage over time¶

curl "https://api.blaick.ai/api/v1/users/me/usage?days=30" \
  -H "Authorization: Bearer $BLAICK_API_KEY"

Query param	Default	Description
`days`	`30`	How many days back to summarize.

{
  "total_tokens_used": 15000,
  "total_cost_tokens": 28000,
  "daily_usage": [
    {"date": "2026-08-03", "tokens": 500, "cost_tokens": 900, "requests": 15}
  ],
  "model_breakdown": [
    {"model_name": "Claude Sonnet 4", "tokens": 10000, "cost_tokens": 20000, "requests": 50}
  ]
}

This is ideal for dashboards: daily_usage drives a time series, and model_breakdown shows where your spend goes.

Token buckets (rollover)¶

Tokens are held in buckets — grants from subscriptions, top-ups, or bonuses, each with its own expiry. Buckets are consumed oldest-first. Inspect them with:

curl https://api.blaick.ai/api/v1/billing/buckets \
  -H "Authorization: Bearer $BLAICK_API_KEY"

{
  "buckets": [
    {
      "id": "…",
      "remaining": 12600000,
      "original_amount": 18000000,
      "source": "subscription",
      "granted_at": "2026-07-15T00:00:00Z",
      "expires_at": "2026-10-15T00:00:00Z"
    }
  ],
  "total_remaining": 12600000
}

Transaction history¶

For a ledger of grants and deductions:

curl https://api.blaick.ai/api/v1/billing/history \
  -H "Authorization: Bearer $BLAICK_API_KEY"

Overage billing¶

Subscribers can opt into on-demand overage so requests keep working past the plan's included tokens, billed as you go.

# Enable
curl -X POST https://api.blaick.ai/api/v1/billing/overage/enable \
  -H "Authorization: Bearer $BLAICK_API_KEY"

# Check status
curl https://api.blaick.ai/api/v1/billing/overage \
  -H "Authorization: Bearer $BLAICK_API_KEY"

# Disable
curl -X POST https://api.blaick.ai/api/v1/billing/overage/disable \
  -H "Authorization: Bearer $BLAICK_API_KEY"

{ "overage_enabled": true, "overage_balance": 150000, "overage_charged_total": 10000 }

Avoid surprise 402s

Before a large batch job, check token_balance (or total_remaining across buckets) and confirm you have enough headroom — or enable overage. A 402 mid-batch means you ran dry.