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 = 1,000 tokens  ·  1 US cent = 10 tokens

Every chat completion reports its cost in the usage object:

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

• 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. This is total_tokens multiplied by the model's cost_multiplier.

Raw tokens vs. billed tokens

total_tokens is what the model processed. cost_tokens is what you pay. A higher-tier model has a larger cost_multiplier, so the same total_tokens costs more cost_tokens. Always use cost_tokens for accounting. See Models for each model's multiplier.

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": 5000,
  "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": 350000,
      "original_amount": 500000,
      "source": "subscription",
      "granted_at": "2026-07-15T00:00:00Z",
      "expires_at": "2026-10-15T00:00:00Z"
    }
  ],
  "total_remaining": 350000
}

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.