> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3iq.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/developers/hosted-gateway) and [Errors](/developers/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.

**List models before you call**

`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 is respected, and machines you've switched to Earn mode are excluded. If a
  model you expect is missing, check that one of your machines is online and
  serving it. See [Route readiness](/operators/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.
- A key can name at most **64** machines. To reach more than that, leave the
  scope empty so the key covers 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_nodes` on every call.
- A per-request pin (`?node_id=` / `b3iq.node_id`) must be **inside** the key's
  scope, or it fails closed with `no_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](/developers/receipts-billing).

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). The quota
resets at midnight UTC. Branch on the code, not the message.

The check is a soft admit: concurrent requests each read the bucket before their
own tokens land, so a burst can overshoot the cap slightly. It is a backstop,
not an exact meter.

## 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](/developers/errors) for
the full list.

## Related

**[Hosted gateway](/developers/hosted-gateway)**

Endpoints, keys, streaming, and the gate order a request passes.
  **[Receipts & payouts](/developers/receipts-billing)**

How completed work becomes signed receipts and operator payouts.
  **[Errors](/developers/errors)**

Stable machine codes, including routing, rate-limit, and quota denials.