Resource allowance accounting
Share budgets, direct limits, reset periods and pending usage.
Start with Resource allowances for setup. A rule belongs to one dedicated resource group in one workspace. Its account membership stays fixed while the rule exists. Members need a direct pool grant and a personal key bound to the rule; an ordinary key is not converted automatically. All of one member's keys for the rule share one ledger.
Share of a total budget
By share accepts a daily/monthly total or up to eight elapsed-duration windows with a separate total for each window. Member percentages total at most 100% and apply to every selected window. Choose one accounting basis:
- By token share: enter the total in M tokens. Reported input plus output tokens count against each member's share; cached input is part of input and is not counted twice.
- By amount share: enter an internal USD total. Each request's input, cached input and output are converted using the model prices saved with that rule revision. These prices do not state the provider's subscription charging formula.
A member's limit in each window is its configured total multiplied by their percentage, rounded down to the smallest accounting unit. For example, a 25% share of a 1 M token budget is 0.25 M tokens. Positive shares that round to zero are rejected. Unassigned percentages and rounding remainders stay unused. Both member and group totals gate admission, including charges from former recipients. The balance spans the resource group rather than resetting for each subscription account.
These are internal budgets. A configured token total does not reveal the subscription's actual capacity, and internal USD is not a cash balance or invoice. SubLane still checks available upstream quota; the provider may reject requests before the internal budget is exhausted.
Time-window amount limits
By time window is a separate allowance type. Add up to eight conditions, each using a whole number of hours or days (from 1 hour to 365 days) and a shared internal USD limit. Select members; each has an independent ledger even when using the same defaults. A member may override individual conditions. Leaving a condition's USD limit blank means unlimited for that condition; its usage is still recorded, without a quota or provisional risk reservation. Every settled request is priced once with the saved model rates and counts in every configured window. New requests stop if any limited condition is exhausted or reaches its provisional risk allowance.
Elapsed windows begin at activation and renew independently. A five-hour renewal leaves weekly usage intact. They are fixed renewing windows, not rolling look-back limits, and do not track upstream subscription resets. The instance time zone changes their display, not their duration.
Member edits and scheduled changes
Choose Edit current members to change shares or direct member limits immediately. Recorded usage and reservations for admitted requests remain. An increase must fit every current shared budget; removal/rejoin never clears usage. For example, with total 100 and A already using 40, caps of 33 each for A/B/C require 106 and are rejected. Caps 40/30/30 fit. Retry after renewal only when all windows can fund the change; scheduling is not a way around a funding gap.
Budget and price edits remain scheduled at the existing pending time, or the current schedule's next boundary (the longest duration for multiple windows). They retain interval alignment and already recorded usage. A shorter window may be in progress when its limit changes; a lower limit can leave it exhausted. A price edit never reprices earlier requests.
Ordinary budget/price edits preserve the saved member section even when a recipient no longer appears in the currently authorized roster. Retaining that instruction does not restore group access. New recipients and a new structural term still require current group permission.
A separate member plan in the upcoming version blocks automatic projection of a current-member edit. Review/cancel that pending instruction explicitly. Other compatible pending price/budget settings are retained. The form does not silently rebase an unsaved draft after a background refresh; on conflict use Refresh and review.
Changing the unit, distribution type, or reset schedule requires confirming a genuine structural replacement. It keeps the rule/group/key IDs and declares a new accounting anchor at its scheduled activation. Price/member changes alone cannot request a fresh accounting period.
Move to next boundary postpones a pending version to the first natural boundary strictly after its saved activation time, using the current schedule (or the pending initial schedule before first activation). Review the server-provided time and confirm it. Changed/expired conditions return a conflict rather than silently moving to another period.
Cancel scheduled change requires an existing current version. An initial pending-only rule cannot be cancelled; pause it or move its start instead. Initial rescheduling replaces the snapshot atomically. Pausing does not cancel/postpone activation or remove the readable configuration, and a paused rule still denies gateway use after activation.
Before first activation, initial member corrections use the full editor (PATCH /api/allocations/{id}). They require the reviewed revision pair and effective time, retain the saved activation and accounting anchor, and recheck target members’ group permissions. This correction path is available only with no current version and no recorded requests. Revision, metadata and audit writes commit together; failure or crossing activation rolls everything back. Initial cancellation remains prohibited.
When an approved next version already has a genuinely different structure from the current version, the existing new-period confirmation is available even if the draft keeps the next version’s structure. Confirm again to edit that pending member allocation. Ordinary pending budget/price edits keep their roster and anchor without reconfirmation. Withdrawing this optional reconfirmation displays and submits the saved member plan. A replacement still requires a genuine structural difference from the current version.
For priced allowances (By amount, By amount share, and By time window), SubLane reads the models supported by the dedicated pool and fills their catalog prices when saving a revision. User-supplied prices do not override this snapshot. If a model has no current catalog price, its previously saved rate is reused when available. A newly discovered model with no price is omitted from the snapshot, so requests to it remain blocked until a priced revision takes effect. Price-coverage warnings are calculated when a rule is read, not stored in its revision: a restored catalog price clears the catalog warning automatically, while a model absent from the saved price snapshot remains flagged until a new revision includes it. Unavailable account catalogs retain previously saved rates and show a warning until discovery recovers. Saving fails only if no usable price remains. Without a loaded price catalog or saved price cache, a new priced allowance cannot be created; refresh the catalog or provide a price fallback before retrying.
For a model missing from a rule's saved prices, the administrator warning shows when a save made now is expected to take effect. In time-window mode this date follows the longest current window, so saving again does not make the new price available immediately. An already scheduled revision instead shows its own effective date and warns that the model will still be blocked after that version starts unless a corrected version replaces it.
Direct limits and pending usage
By tokens sets a member's token limit directly. By amount sets a direct internal USD limit using saved model prices. Both use the same token or price accounting as the corresponding share basis.
Completed requests with known usage are charged without waiting for upstream percentage updates. A dispatched request without trustworthy totals remains pending for correction; partial counts stay visible but are not settled charges or reservations. Each active request provisionally reserves 10% of its captured member limit in each finite window, at least one unit. Later edits do not resize that reservation. Each finite window allows at most four in-flight requests per member within that window; shared budgets also check group exposure. Requests release reservations when they end. These are soft admission limits: a large admitted request can finish above member/group limits, and missing usage leaves incomplete exposure. The newest 256 pending entries are shown first; older entries reappear after correction. Allowance attribution uses successful admission time after queue waiting; diagnostic duration still begins at arrival.
For Codex streams, SubLane may keep reading upstream for up to 3 seconds after the client disconnects to capture trustworthy final usage. A failed terminal event that includes complete usage can also be charged. Repeated upstream failures cool the affected account temporarily; a successful response without final usage remains pending without cooling the account. If an accounting write fails temporarily, SubLane retries that request before admitting more allowance-backed work for the affected member; other members can continue.
Daily/monthly rules keep their chosen instance-time-zone clock/date. A missing monthly date falls back to the month's last day; defaults are 00:00 daily or day one at 00:00 monthly. Ordinary edits preserve accounting anchors. Pausing or revoking access blocks subsequent requests and WebSocket turns without erasing history. Upstream quota refresh, reset cards, reauthorization, and process restart do not refill local budgets.
Choosing Start next period when creating a time-window rule starts it after the longest configured duration.
Read and correct balances
Members see their own allowance under Usage. Workspace administrators open Resource allowances → View usage for the full rule. All configured time windows appear under one member with their own limit, used amount, remaining amount, risk exposure, and reset instant; the member status reflects the most restrictive condition. Amount balances show internal USD alongside reported tokens; token balances use M, where 1 M = 1,000,000 tokens. Personal reports do not expose subscription-account identities.
The balance separates used (settled usage) from in-flight requests and pending usage in the current cycle. Temporary reservations reflect only in-flight requests; pending usage remains visible for correction and does not count as used allowance or reserve capacity. Admission headroom includes the automatic risk buffer; it is not extra spendable allowance. A positive remaining allowance can therefore coincide with New requests temporarily paused when another request needs more reservation than the current headroom, or four requests are still in flight. The status follows the same current-cycle risk check as gateway admission. It is a snapshot and can change as requests finish. Pending records outside the current cycle remain visible for correction but do not pause its admission.
When a pending entry cannot be resolved automatically, an administrator may enter input, output and cached-input totals supported by trustworthy evidence. The correction uses the request's saved accounting rule and writes an audit event. Do not treat missing usage as zero or enter invented totals.
Workspace administrators manage rules at /api/allocations; members read their own balances at /api/me/allocations. Keys bind to a rule with scheme_id. See workspaces and personal API keys.
API write conditions
Reads retain their existing envelopes and expose additive write_conditions with nullable expected_current_revision_id and expected_next_revision_id. Both fields are mandatory on existing-rule configuration writes, including full PATCH, members, cancellation/rescheduling and replacement. Missing/stale conditions return HTTP 409 without changing configuration. Do not fetch new IDs and retry a stale payload automatically. Existing explicit enable/pause and request-bound settlement operations retain their own contracts.
Future-revision writes additionally require the server-confirmed UTC-second expected_effective_at; structural replacement requires confirm_replacement=true. Preview existing schedules at POST /api/allocations/{id}/preview with action schedule, reschedule, or replace. Member updates use POST /api/allocations/{id}/members; pending actions use POST /api/allocations/{id}/cancel and POST /api/allocations/{id}/reschedule. Full saves cannot mutate access enablement; use POST /api/allocations/{id}/enabled separately.
First creation without a time condition keeps legacy immediate/delayed behavior. A client opting into expected_effective_at must use start_next=true: calendar starts must match the next boundary, and duration starts must remain future and within one longest duration of server time. Explicit null is a required-condition conflict, malformed input is HTTP 400, and expired/changed time is HTTP 409. POST /api/allocations/preview returns the initial proposed time without creating a rule. A failed confirmation never falls back to unconditioned creation.