Billing & Usage

Every account has two billing meters. Each run settles on exactly one, decided by whether the run is for one of your end users:

The axis is first-party vs embedding, not which transport you used. An API key calling without user_id is still your own work, so it settles on the plan; the web app and that call bill the same way. New API accounts are created in strict multi-tenant mode, where user_id is required on every run — so unless you deliberately turned that off to build single-tenant, every one of your API runs carries a user_id and bills from the prepaid balance.

The two never fund each other. Plan credits cannot pay for balance-metered runs and the balance cannot pay for plan-metered ones: a paid plan does not top up your balance, and a depleted balance is not rescued by unused plan credits. So an end-user run leaves your run count untouched, and a first-party run leaves your balance untouched.

It follows that a paid plan does not come with end-user API usage. If you do both, you fund both: the subscription for your own runs, and a topped-up balance for your end users'.

New API accounts start on the prepaid balance with $5 of token credits, free and one-time: no run tier, no subscription.

Plan usage

What counts as a billable run? One execution that completes with output: manual, scheduled, webhook, email, reply, or retry. On the plan meter, failed runs that produce no output don't count against your included runs.

usage.plan returns a stable slug: trial (time-boxed, 50 runs, one-time), free (50 runs per rolling 30 days, runs on the account's own Claude subscription), pro (100 runs/month), max_5x (Scale, 500), or max_20x (Enterprise, 1,000). Browse the live catalog, prices included, with client.billing.plans() — free is activation-only, so it is not in that purchasable list.

Usage overage

Opt in to keep running past your plan's included runs, billed per run up to a monthly cap you set:

Details: how overage kicks in

• When the included allotment is exhausted, a run returns 402 RUN_LIMIT_REACHED with overage_available in error.details — true only when overage can actually be enabled for your account.
• Enabling overage requires an active subscription it can be billed to; without one (e.g. trial or free) overage_available is false and the call returns 402 OVERAGE_UNAVAILABLE.
• See errors.

Prepaid balance

Each API run debits a micro-USD balance at the provider's list prices; plan run limits and overage don't apply to this meter. A failed or cancelled run that consumed tokens is still debited, because those tokens were already spent with the provider. A retry is a separate run and a separate debit. Top up to add credit: topup() starts a Stripe Checkout and returns the checkout URL.

When the balance is depleted, a run returns 402 TOKEN_BALANCE_DEPLETED; the SDK raises BillingError with .details carrying balance_micros and a topup_url. Recover by topping up, or connect your Claude subscription if you are developing locally. See errors.

Details: top-up mechanics and signup notes

• Top-ups are $5 minimum per charge and available to every account, including plan accounts funding API usage.
• The balance is credited asynchronously once payment completes (after the checkout.session.completed webhook), so balance() won't reflect it until then.
• Any completed top-up Checkout saves your card, which enables auto reload.
• balance() also returns the recent transaction ledger: top-ups, reloads, per-run debits, and adjustments with balance_after_micros for each.
• Signup dedupes alias-collapsed emails: plus-tags (you+anything@…) always map to the base mailbox, and Gmail dot variants collapse too. An address that aliases an existing account is rejected as already registered.

Develop on your Claude subscription

Testing the API locally does not have to spend your balance. Connect your personal Claude Pro or Max subscription at m8tes.ai/account (Authorize with Claude) and every run on your account bills your subscription's quota instead of the prepaid wallet — the balance is not touched, and a depleted balance does not block you. Disconnect the credential to switch back to wallet billing.

Details: scope and caveats

• Best for local development. Consumer subscriptions carry Anthropic's own usage windows and rate limits, and using one inside a third-party tool is at your own risk under Anthropic's consumer terms. Production and multi-tenant traffic should stay on the prepaid balance.
• The credential is account-level: it covers every run on your account, including runs created with a user_id. Per-end-user credentials are not supported.
• Subscription runs use Claude models. Any non-Claude model choice, including an explicit one, falls back to the default Claude model for the run (the run records the model it actually used).
• Each run records how it was paid: run.auth_method is "oauth_subscription" on the subscription, "gateway_virtual_key" or "api_key" on the wallet.

Auto reload

When the balance falls below your threshold, m8tes charges your saved card the reload amount and credits it automatically:

Details: card requirement and reload cadence

• Any completed top-up Checkout saves your card; enabling auto reload without one returns 402 NO_SAVED_PAYMENT_METHOD.
• Reload amounts run from $5 to $10,000 per charge (lower than the manual top-up ceiling; these charges happen off-session).
• At most one reload fires per 6-hour window, so a declined card is never retried on every run, and Stripe emails a receipt for each charge.
• Reloads appear in balance() transactions and in receipts() alongside manual top-ups.

Spend alerts

Three escalating alerts fire as the balance drains (low, critical, depleted). Each sends an email and a webhook event so your systems can react, for example by triggering your own top-up flow.

Details: alert tiers

Tier	Fires when	Webhook event
Low	balance ≤ your threshold (default $5)	balance.low
Critical	balance ≤ 20% of the threshold	balance.critical
Depleted	balance ≤ $0, runs fail until you top up	balance.depleted

Each tier fires at most once per depletion cycle; all three re-arm on the next top-up.

Usage over time and receipts

Details: timeseries semantics and per-run metrics

• usage_timeseries() returns daily token + USD buckets, zero-filled over the window (default: last 30 UTC days), reconciling with usage().cost_used and prepaid debits.
• Filter with user_id (one end-user) or agent_id; pass group_by="model" for per-model slices in each bucket.
• teammate_id is the wire name for the agent id: query params and JSON bodies keep it. The SDK accepts agent_id (canonical) and teammate_id alike.
• Every run response also carries per-run metrics: run.usage has the token lanes (input/output/cache) and cost_usd, the exact figure billing meters. It's None until the run produces metrics.

Per-end-user caps and usage

Multi-tenant accounts can cap each end-user's runs, cost, and rate, and break the billing period down per end-user with client.users.usage(). See Users.

Next: Users · Limits · Errors