Skip to Content

Quotas and credits

Four different values can affect a subscription request:

ValueMeaning
Included quotaThe provider’s allowance for an account, model or product surface over its own windows
Paid credits/overageProvider-reported funding outside the included allowance
Modem allowance/rate limitRules on the relay’s project/product/customer that admit a request
Estimated provider costThe request’s token usage valued at comparable API prices; not a subscription charge

A successful quota read does not reserve capacity. Another client can consume the same account’s allowance before the relay sends its request.

Read subscription details

Open Credentials → Subscriptions, then select an entry. Details show the plan, observed quota windows/reset times and provider-specific balances when available. Reported credits, reset credits, on-demand spending/limits and prepaid balances occupy separate details; providers do not all expose the same concepts.

Unavailable data stays unavailable. A missing credit field does not mean zero credits, and an unreadable quota does not mean unlimited usage. An overage such as 104% used preserves what the provider reported; it is not silently rewritten as a fabricated remaining balance.

Account-wide, model-specific and surface-specific windows remain separate. A depleted window blocks the scope it applies to; it must not be interpreted as exhaustion of every unrelated model. Short and weekly windows can reset at different times.

Inspect an account through the admin SDK

Create an admin key with workspace subscription-sign-ins:read for listing and subscription-sign-ins:write for inspection: inspection is a POST because it can renew stored credentials. Use list to obtain a saved sign-in ID, then inspectAccount:

import { createAdminClient, readAdminApiKeyFromEnv } from '@preternatural-js/admin-sdk' const apiKey = readAdminApiKeyFromEnv() if (!apiKey) throw new Error('Set PRETERNATURAL_MODEM_ADMIN_API_KEY') const admin = createAdminClient({ environment: 'production', apiKey }) const signInId = '<saved-sign-in-id>' const { account } = await admin.subscriptionSignIns.inspectAccount(signInId) switch (account.status) { case 'available': // accountLimits is deliberately unknown at this SDK boundary. // Use a provider-aware decoder before reading individual windows. console.log(account.plan, account.paidCredits?.hasCredits) break case 'rejected': console.error('Sign in again:', account.reason) break case 'failed': console.error('Account read unavailable:', account.kind, account.reason) break }

The response is { signInId, account }, not the normalized quota rows displayed in the app. An available report can include plan, opaque accountLimits, and optional paidCredits flags (hasCredits, unlimited); those flags do not supply a numeric credit balance. Never cast accountLimits to a guessed ChatGPT shape for Grok or Claude. The app uses provider-aware projection for windows and balances.

Calling inspection again requests the current usage observation; it can reuse a fresh cached result and has no force-refresh argument. A provider read can renew credentials, so rejected renewal can also fail the HTTP operation rather than arriving as an account.status branch. Handle admin API errors separately from the account result. Repeated inspection is not a substitute for reconnecting rejected authentication.

Inspection does not return the available models or refresh the model cache. admin.models.list() is the public gateway catalog, not an entitlement check for one subscription. To choose a subscription-native model, use a relay’s generated native-client setup and its advertised model list; a multiplexed list is the union of its observed members. A catalog entry does not guarantee remaining quota or a successful request. The current public admin SDK has no standalone per-sign-in model-list or normalized-quota method.

Freshness

Models and usage are independently cached against the account identity and credential revision. Successful observations are fresh for up to five minutes, with quota freshness shortened by an earlier reset. Failures have a short retry interval. A still-fresh successful field can survive an unrelated transient failure; rejected authentication does not preserve it as a valid signed-in observation.

Use observation timestamps when diagnosing differences from a provider’s native UI. Changing credentials/account identity invalidates previous observations. Refreshing details is not proof that every API response was fetched from the provider again.

Claude reports

On Claude-enabled deployments, local status-line and Agent SDK observations can supply quota details that a direct account read cannot obtain. A local report is not a usable server-held login and cannot by itself back a relay. Reported windows remain valid according to their reset time; windows without a reset and balance details use short freshness limits. A retained local report is not a fresh network read.

To forward a real status-line payload from a native integration:

modem-cli subscription-signins report-claude-quota \ --installation-id '<stable-installation-name>' \ --source status-line < '<status-line-payload.json>'

For an Agent SDK usage payload use --source agent-sdk. Keep a stable installation ID so updates relate to the intended local installation. Report provider-derived values only; do not manufacture a quota response to force account selection.

The current Claude default prefers reported quota. A provider observation may explicitly permit trying without paid usage even when another displayed reading is exhausted; that is treated as uncertain eligibility, not proof of replenished quota. A fresh refusal/block still takes precedence. Codex/Grok use their own included-quota checks.

Choose credit permission and timing

Credits are disabled by default. Permission is per relay membership, so the same subscription can allow credits in one link and forbid them in another.

TimingSelection behavior when included quota is exhausted
immediateAn eligible account may use permitted credits before moving to the next member’s included allowance
deferredConsider included allowance elsewhere first; spend deferred credits in configured subscription order

With deferred funding on all members, the selected default considers unverifiable included quota before deferred paid credits. A reported balance is only an observation, not a reservation or a guarantee that the provider will accept the request.

Configure membership options through the admin SDK. Use the authenticated client and relay ID from the membership example, with workspace subscription-sign-ins:read and subscription-sign-ins:write permissions:

const current = await admin.subscriptionRelays.getMembership(relayId) const firstId = current.primarySignInId await admin.subscriptionRelays.updateMembership(relayId, { expectedRevision: current.revision, signInIds: current.subscriptions.map(member => member.id), memberOptions: { [firstId]: { credits: { useWhenExhausted: true, timing: 'deferred' }, }, }, })

Here admin is an authenticated admin client and relayId is the link ID. Only entries included in memberOptions are replaced. An empty object for a member resets that member’s overrides to server defaults. The current app membership editor exposes ordering, not these funding controls; the CLI’s set-members command does not set funding options.

Multiplexed quotas are not additive percentages

Two accounts with 30% left do not become one account with 60% left. Allowance sizes, reset times and applicable scopes can differ. Inspect each member’s windows and the selected account’s eligibility. A native billing endpoint using the primary identity is not a composite balance.

Interpret cost estimates

Modem can estimate an API-equivalent value using provider token counts and model reference prices. This does not say what a subscription charged or how many paid credits it consumed. Missing token counts or prices leave that estimate unavailable instead of substituting zero.

If a request may have run but its terminal usage was lost, actual usage/credit consumption can remain unknown. Repeating that request may consume allowance again. See uncertain outcomes.

Last updated on