Usage and cost estimates

Usage is your deployment’s own record of the model work it did: one operation per Slack message an Agent answered, per run of a schedule, and per routing classification, each carrying the tokens the provider reported. Where your model provider’s dashboard bills every key it holds, Usage covers only the work this deployment handled and prices it from a catalog pinned at release rather than from an invoice. This page covers what is recorded, what is never recorded, how the estimate is built, how long the data lives, and the three switches that turn each layer off.

What is recorded

Chickpea keeps two ledgers.

Model operations. An operation opens when a turn is admitted and closes with a measurement when the turn ends. There are three kinds: an interactive turn, a run of a schedule, and the classification call that decides whether an explicitly addressed message needs an answer. Each operation carries the Agent, the channel or the fact that it was a direct message, the provider and model requested, the provider and model that answered, the model credential reference and its version, and a status of admitted, completed, failed, interrupted, or incomplete. Each measurement carries input tokens, output tokens, cache read tokens, cache write tokens, and a total.

Connector attempts. A call through a managed connection writes one attempt row: the toolkit, the capability, the outcome (success, validation_failed, authorization_expired, throttled, provider_unavailable, or ambiguous), latency, remote call count, result size in bytes, HTTP status, rate-limit headroom, and any retry-after delay. Only the managed lane records attempts.

What is never recorded

• No message content. The usage tables hold identifiers, labels, counts, and timestamps. Prompts, completions, message text, and tool arguments have no column to go in.
• No credentials. A model key is recorded as an opaque credential reference and a version number, never as the key itself.
• Labels are checked before they are stored. An Agent, channel, or schedule label is rejected if it exceeds 160 bytes, contains a disallowed control character, or looks like a credential.

How the estimate is built

The estimate is advisory and Chickpea says so in its own metadata: token counts come from the model response aggregate, money is a Chickpea list-price estimate, provider billing is not included, and Chickpea manages no limits.

• Prices come from a release-pinned catalog. One dated catalog ships with the release. It covers claude-haiku-4-5 on Anthropic, gpt-4.1-mini on OpenAI, openai/gpt-4.1 on OpenRouter, and @cf/zai-org/glm-5.2 and @cf/zai-org/glm-5.3-flash on both Cloudflare Workers AI routes. A model outside that list records tokens and reports price_unknown.
• A catalog entry expires 90 days after the date it was reviewed. After that, operations record the reason price_stale instead of an amount, and Admin shows a line saying spend estimates need a pricing update.
• Only complete token reporting is priced. If the provider reported partial usage, or the stream was interrupted, the operation is metered as far as it can be and left unpriced with an explicit reason.
• Amounts are stored in millionths of a currency unit. Every catalog entry in this release is priced in USD.
• Discounts and tiers are not modelled. Cache pricing is modelled only where the catalog carries a cache rate. Batch and priority tiers, negotiated pricing, credits, free allowances, and taxes are deliberately left out.

Connector attempts through Composio are estimated the same way, from a dated component price list, before free allowances, plan credits, and negotiated discounts.

The Usage section in Admin

Usage is a section of Admin alongside Agents, Team, Settings, and Audit logs. It requires the admin.configure permission, which Owners and Admins hold and Members do not.

• Period. Last 7 days, Last 30 days, Last 90 days, This month, Last month, This week, Last week, or Custom. A custom range may not end in the future and may not exceed 366 days, which is also the ceiling the query layer enforces.
• Break down by. Channel, Agent, provider, or model.
• Four cards. Estimated spend, Activity, Tokens, and Average spend, each compared with the immediately preceding period of the same length.
• Recent activity. A table of individual operations with channel, Agent, provider, model, status, tokens, and spend. Classification operations are excluded from both the totals and this table.
• A coverage line. When some activity did not report token usage, Admin states how many of the period’s activities the totals include.

One sentence sits above the numbers on every load: “Set spending limits with each model provider; Chickpea reports estimated spend for activity it handles.”

A schedule whose results are delivered to a direct message is excluded from every Usage query and returns a not-found error if addressed by ID. Connector attempts are recorded and queryable through the Admin API, but the Usage section does not display them today.

Where usage data lives

Retention

• Raw operations and measurements are kept for 90 days. On expiry they are folded into a daily rollup and the raw rows are deleted, so the totals for an old day survive without the detail behind them.
• Daily aggregates are kept for 13 months.
• Connector attempts follow the same clock. Raw attempts expire at 90 days, connector daily rollups at 13 months.
• Cleanup is opportunistic. It runs on a usage write when more than 24 hours have passed since the last run, and a failure is logged and skipped rather than allowed to block recording.

The switches

Each layer is independent. Any value other than unset, 1, or true disables it.

One more variable is not a switch. CHICKPEA_INSTALLATION_ID sets a non-secret accounting label stamped on every operation, and defaults to chickpea when unset or malformed.

Why it works this way

Recording is additive and fail-open. Each usage write gets a budget of 100 milliseconds, bounded to 250 milliseconds at the most, and a write that times out or fails never delays or blocks a reply. The recorder marks itself for repair and tries once more after the turn finishes.

Prices are pinned to a dated catalog rather than fetched live because a live price lookup is a network dependency on every turn and a number that can change without notice. A pinned catalog gives a figure you can reproduce, and an expiry date that makes an out-of-date figure say so instead of quietly drifting. Tokens and money are recorded separately for the same reason: the token counts come from the provider’s own response, and the price does not.

What is not covered

• Usage is not your bill. Provider limits and spend apply to the whole key, project, or account, including work outside Chickpea. Set spending limits with each model provider.
• Chickpea enforces no budget. Nothing stops or throttles work when an estimate crosses a number.
• Infrastructure is not counted. Workers, Durable Objects, D1, Workers AI, and optional coding sandbox usage run in your own Cloudflare account and may incur costs there. None of it appears in Usage.
• A custom or local provider records operations only. Chickpea cannot infer a billing boundary or a price contract for a route it did not ship a catalog for.
• Old detail does not come back. After 90 days the per-operation rows are gone and only the daily totals remain.

Next steps

• Admin: the rest of the browser app, including roles and the management MCP.
• Models and providers: pinning a model per Agent, and which providers a deployment can use.
• Data and storage: what a deployment stores, and what leaves it.
• Environment variables: the environment variables named above, with their exact accepted values.