Usage & Quotas
Inference on your own machines is free — how usage is metered per key and account, what rate limits apply, and how the optional per-account token quota works.
Inference through the hosted gateway is free. There is no prepaid balance, no credits, and no per-request charge. Instead, your API keys route requests to the machines on your own account, and the gateway meters usage per key and per account so you can see exactly what ran.
For how requests select supply and what each error means, see Hosted Gateway and Errors.
Your Keys Route To Your Machines
A gateway key dispatches only to machines claimed to the same account (or an organization fleet you belong to). That is the whole model:
- Have a machine on your account that is online and serving the model you request. Requests then complete free of charge.
- If no machine on your account can serve the requested model right now,
the request fails closed with the stable code
no_eligible_nodes(HTTP 404) instead of silently running somewhere else.
GET /v1/api/models, called with your gateway key, returns exactly the
models the machines on your account serve right now — any node scope on the
key respected, with machines you've switched to Earn mode excluded. If a
model you expect is missing, check that one of your machines is online and
serving it — see Route readiness.
Scope A Key To Specific Machines
By default a key reaches every machine on your account, including ones you add
later. You can narrow a key to a subset at creation — in the dashboard, turn on
Limit to specific machines and pick them; over the API, pass a node_scope
array of machine ids to POST /api/dev/keys.
- Leave it empty (or omit it) to cover every machine on the account.
- Every id must be a machine on your account at creation time — an unknown or
unowned id is rejected with HTTP 400, so a typo fails loudly instead of minting a
key that silently returns
no_eligible_nodeson every call. - A per-request pin (
?node_id=/b3iq.node_id) must be inside the key's scope, or it fails closed withno_eligible_nodes.
Usage Metering
Every request is metered — token counts, model, duration, and outcome — and recorded against the key that sent it and the account that owns the key.
- The dashboard Usage view shows requests and tokens per key and per account over time.
- Completed requests still record public-safe receipt evidence; see Receipts & payouts.
Metering is for visibility and quota enforcement, not billing — a metered request does not cost anything.
Rate Limits
Request rate limits protect the network and your own machines:
- Per-key requests-per-minute cap, optional per key. Blank (or
0) means no per-key cap — your own machines, your throughput. Set a value (1–10000) and it is enforced on every request the key sends, your own machines included. - Per-account ceilings that apply across all keys on the account (a per-minute window plus the daily token quota) — always enforced as the abuse ceiling, even when a key has no per-key cap.
Exceeding a limit returns HTTP 429 with an OpenAI-compatible
rate_limit_error envelope. Back off and retry after the window resets.
Token Quota
Accounts carry an optional daily token quota set by the B3IQ team. The default is uncapped — most accounts never hit a quota.
When a quota is set and exhausted, requests fail closed for the rest of the
day with the stable code account_token_quota_exceeded (HTTP 429). Branch on
the code, not the message, and resume when the window resets.
When Requests Fail Closed
Hosted requests are denied — rather than misrouted — when they cannot be served under your account:
- No machine on your account serves the requested model (
no_eligible_nodes). - The model or route is outside your model allowlist or route-tier policy.
- A per-key or per-account rate limit is exceeded.
- The account's daily token quota is exhausted (
account_token_quota_exceeded).
Each case returns a stable machine code. See Errors for the full list.