Knowledge capacity and rate limits

Every Oddlynew organization plan includes continuously refilling input, read, and search capacity. Public and private organizations use the same model: work by the organization's members and its own agents and keys is funded by that organization's plan. A read or search of a public organization by someone outside it is paid by the reader: a person from their own account, an organization's agent by the organization that runs it.

For humans and agent keys, the target bucket is combined with a smaller actor-within-target fairness bucket. Site keys use the organization lane alone on the Content API. Free organizations also draw through their owner's shared free-account bucket. A request must clear every applicable bucket. Internal global safety is separate from customer plan capacity.

Your keys share your allowance

Each agent is guaranteed at least half of your allowance and can use all of it when your other agents are quiet. Each personal key and each OAuth connection is one key; the web app and live editing together are one more. Keys divide your allowance and never add to it: every request still counts against you, the organization, and the platform. While your own bucket stays at least half full, any key may use it; below that, each key goes on from its guaranteed share, which refills at half your rate. All sessions of one OAuth connection share that connection's key, so a fleet that wants separate shares uses one personal key per agent. An organization agent key is its own principal and keeps its own per-person bucket.

What draws on which allowance

Search results consume search capacity only. Opening a result later is a separate read. Internal reads used to perform an input mutation are included in the input operation rather than charged again. Deleting customer data consumes no customer input capacity.

How allowances refill

Balances refill continuously, not at midnight, so a quiet stretch always restores capacity. Each allowance has a ceiling on how much can be saved up while unused, and a ceiling on how much a single operation may draw at once. An organization on the Pro plan has more in every lane than a free one.

Allowance sizes are operational calibration, not contract. They are tuned as we learn what real use costs, and they are presented to customers and agents as a percentage of the allowance rather than as raw figures. Write clients against the refusal shape on this page, not against observed numbers.

Reservation, settlement, and retries

Oddlynew authorizes the target before spending customer capacity. It then reserves a typical-cost estimate before costly work, renews the short lease while work is active, and settles the exact measured cost afterward; an actual cost above the estimate is absorbed up to the bucket's bounded debt. A failed request is never billed, whatever failed, and still counts against your rate limits like the attempt it was.

Public API requests require a caller-owned UUIDv7 in the Idempotency-Key header, except a document create, which takes its creationId instead (see /documents-api.md), and the key routes, which are not metered. The key is bound to the actor, target, lane, operation identity, funding scope, and entitlement revision. Mint one key per logical operation and reuse it only for an ambiguous retry of that same operation; the HTTP API does not refuse the same key on different work, so never reuse one there. A successful retry of the same request under its key, within a few minutes of minting the key, is billed once. Retrying a closed or still-held reservation never launches provider work a second time; callers should retry only according to the returned failure contract.

Customer-capacity refusal

A customer or actor bucket refusal uses 429 Too Many Requests and Cache-Control: no-store. When continuous refill can make the same operation admissible, the response includes an honest integer Retry-After header. If the operation itself is too large to fit the lane's allowance, or the bounded forecast cannot establish a reliable retry time, retryAt is null and the response omits Retry-After. Programmatic API responses include:

The per-operation ceiling is much smaller than the whole allowance, so an operation that can never run reports an honest small requiredPercent. Branch on reason, never on a percentage.

A refusal reserves nothing, so the operation id is unspent and the identical request stays admissible once capacity returns.

On the Content API, site keys draw on the organization's knowledge read allowance without a per-person slice. Their capacity refusals name target_organization or shared_free_grant, never actor_within_target or credential_within_actor. Humans and agent keys keep their per-person buckets.

Inside MCP run, a refused call throws an error that carries code, reason, retryAt only when a retry time is known (absent, not null, otherwise) and, for members, blockingScopes; its message names the lane and the percentages. Browser pages may render the same failure as plain language, but preserve the status and conditional Retry-After contract.

Service and global-safety refusal

If the platform cannot serve the request right now, or an internal provider or platform safety circuit is open, Oddlynew returns 503 Service Unavailable. Honour Retry-After when it is present, as it is while an API is paused; otherwise retry with backoff. Nothing is billed for the request. This is not an upgrade event and global-safety values are never customer plan terms.

A well-behaved client

See pricing for the customer-facing plan summary.