Last reviewed: 2026-08-11

Direct answer

Do not budget a reasoning-capable request as if its visible answer were the whole billable workload. Keep three separate measures in the CometAPI cost ledger: input tokens, internal reasoning or thinking tokens, and visible output tokens. Add the provider route, model, reasoning setting, response status, and pricing snapshot to every aggregate. Then compare the planned reasoning allowance with actual usage over a representative sample before changing a team or workload budget.

The practical rule is simple: a reasoning setting is a control input, not an invoice. OpenAI describes internal reasoning tokens and shows them as a distinct usage detail. Anthropic exposes a thinking-token count alongside a configurable budget_tokens target. Gemini reports total thought tokens for thinking interactions. Those names and billing rules differ, so a gateway ledger should preserve the raw provider fields and also maintain a small normalized view. If a response has no breakdown, mark the reasoning component as unknown; do not quietly fold it into visible output or report a false saving.

Use this happy path for each new workload:

  1. Define the unit. Choose a stable unit such as one customer task, one agent turn, or one completed batch item. Record the route and model alias that actually served it, not only the application model label.
  2. Set a baseline. Before changing effort or thinking controls, run a representative sample. Capture input, reasoning, visible output, total, latency, completion status, and any provider-specific usage fields.
  3. Calculate with separate rates. Apply the current route price snapshot to each billable component. Where the provider says reasoning is billed as output, use the output rate for that component; where the gateway supplies a combined total, keep the allocation provisional and label it.
  4. Review quality and spend together. Compare reasoning tokens per successful unit, visible answer length, retries, and task quality. A smaller reasoning allowance is not a saving if it creates rework or extra calls.
  5. Approve with a guardrail. Set a per-unit target, a p95 review threshold, and an escalation threshold. Revisit them whenever the model alias, provider route, or reasoning mode changes.

The error path is equally important. If the gateway returns only a total, preserve the total and set reasoning_tokens: null; route the record to an exception queue. If a provider rejects a thinking configuration, record the status and model, fall back only to a documented supported mode, and require a new baseline. If a request reaches a token limit before producing visible text, count the incurred input and reasoning work and flag the unit as unsuccessful. Never turn a missing field into zero.

Who this is for

This is for FinOps owners, platform engineers, and product leads who approve AI API budgets across several model families. It is especially useful when one CometAPI integration can send similar work to different reasoning-capable routes, or when a team has adopted an effort or thinking control and expects an immediate cost reduction.

It is not a model-selection scorecard by itself. The goal is a trustworthy cost ledger that lets a reviewer answer three operational questions: what work was requested, how much internal reasoning was performed, and what useful visible result was delivered? If your current ledger already records only a single token total, start with a sampled retrofit rather than attempting to reconstruct every historical call.

Key takeaways

  • Treat the reasoning allowance as a request setting and the actual reasoning count as usage evidence.
  • Keep input, internal reasoning, visible output, and total tokens in separate columns.
  • Store the serving route and resolved model alias so a later price review can reproduce the calculation.
  • Use null or unknown for an unavailable breakdown; zero means the provider explicitly reported zero.
  • Review cost per successful unit, not cost per response, so truncated or failed work is visible.
  • Rebaseline after a model, reasoning mode, gateway mapping, or pricing snapshot changes.

Sources checked

The OpenAI reasoning models guide explains that reasoning models use internal reasoning tokens before producing a response and shows a separate reasoning-token usage detail. It also warns that a request can reach a token limit before visible output appears, which is why an incomplete response must not be treated as free.

The Anthropic extended thinking documentation describes a budget_tokens target and the response field usage.output_tokens_details.thinking_tokens. It notes that actual thinking can stop below the target and that the total output ceiling still matters. That distinction is the basis for recording both configured allowance and observed usage.

The Google Gemini thinking guide describes thought steps, optional summaries, and a completion usage object that includes total_thought_tokens. A thought summary can be empty or absent, so summary text is not a safe proxy for the amount of thinking performed. The usage count belongs in the ledger instead.

These sources are provider documentation, not a promise that every CometAPI route exposes identical fields. Use them to define the questions your gateway adapter must answer, then verify the actual response and invoice behavior for the route you operate.

Contract details to verify

Before a budget owner signs off, verify the contract at four layers.

Field mapping. Keep a raw usage object, then map it to input_tokens, reasoning_tokens, visible_output_tokens, and total_tokens. For Anthropic, the observed thinking count is nested under the output-token details. For Gemini Interactions, the completion usage uses a thought-token total. For OpenAI, retain the reasoning-token detail shown by the Responses API. Do not rename a missing field to zero during parsing.

Configuration semantics. Store the exact normalized setting and the raw provider setting separately. Anthropic’s manual budget_tokens is a target for the internal process, not a guarantee that the model consumes the full amount. Other routes may use an effort or dynamic-thinking control. A setting change should create a new ledger cohort, not overwrite the old one.

Billing unit. Confirm whether the route charges reasoning as output, combines it with output, or exposes a separate line. Apply the current price snapshot at the time of reconciliation. Do not copy a rate from another model family just because the visible API shape looks similar.

Success definition. Define what counts as a completed unit: a valid structured result, a resolved support case, or a successful tool-assisted task. Track incomplete and retried units separately. A cheap failed answer can be more expensive than a longer successful answer once rework is included.

A compact sanitized record can look like this:

{
  "workload": "support-triage",
  "route": "reasoning-route-a",
  "model": "model-alias",
  "reasoning_setting": "medium",
  "input_tokens": 1200,
  "reasoning_tokens": 870,
  "visible_output_tokens": 430,
  "total_tokens": 2500,
  "usage_source": "response_usage",
  "status": "completed",
  "price_snapshot": "2026-08-11"
}

The values are illustrative counters, not a provider quotation. Keep request content, user identifiers, and authentication material out of this cost record. A hash or internal workload label is enough for aggregation; the ledger does not need prompts or private data.

Failure modes

The gateway returns only total tokens. This is an observability gap, not evidence that reasoning was absent. Preserve the total, mark the component split unknown, and use a conservative budget until the adapter can retain provider usage details.

A budget is mistaken for actual usage. A 10,000-token allowance does not prove that 10,000 tokens were generated. Keep configured_reasoning_budget conceptually separate from reasoning_tokens observed in the response.

A thought summary is counted as thinking usage. Summaries are presentation data and can be empty. Reconcile with the numeric usage field, never with the number of words in a summary.

A model rejects the requested mode. Providers can deprecate a manual mode or reject an unsupported setting. Capture the HTTP status and safe error class, stop the automatic budget change, and route the workload to a tested fallback. Do not label the fallback cohort as equivalent until it has its own sample.

The request ends at a token limit. A response with no visible answer may still have consumed input and reasoning tokens. Mark it unsuccessful, record the incomplete reason, and include the spend in the failed-unit rate.

The model alias moves. An alias can point to a new model family with different reasoning behavior or prices. Resolve and store the serving model on every record, then open a rebaseline when it changes.

Retries hide the real unit cost. Join attempts under a workload unit and report both attempt spend and successful-unit spend. This prevents a lower per-attempt number from disguising a higher rework bill.

For related governance, use the approved CometAPI reasoning-effort guardrails article, and pair the ledger with the token usage evidence for budget reviews .

FAQ

Are reasoning tokens always hidden from the user? Not necessarily. Providers may return encrypted signatures, summaries, or thought steps while keeping the numeric accounting separate from visible text. For cost control, use usage fields and the route’s billing contract rather than assuming that anything not displayed is unbilled.

Should the configured reasoning budget become the monthly budget? No. It is a per-request control. Multiply observed usage per successful unit by realistic volume, then add a failure and variance allowance. Revisit the estimate after the workload has enough completed samples.

What if CometAPI normalizes all providers to one usage shape? Keep the normalized fields for reporting, but retain the raw provider name and route beside them. A shared schema is useful only when its mapping rules and missing-field behavior are documented and testable.

How much data is enough for a first review? Use a representative sample spanning normal and difficult requests, then compare median and p95 reasoning tokens per successful unit. The exact sample size depends on workload variability; the important control is to record the cohort and confidence level instead of presenting an early estimate as a guarantee.

Where should a team start if it has no reasoning-token telemetry? Add the fields to a shadow ledger, run a small sample without changing the production setting, and compare the gateway response with the provider’s documented usage shape. Hold any budget reduction until missing fields and incomplete responses have an owner.

Reader next step

Create one worksheet for each route with these columns: workload unit, resolved model, reasoning setting, configured allowance, input tokens, reasoning tokens, visible output tokens, total tokens, status, successful-unit flag, and price snapshot. Sample the current workload, reconcile the raw response fields, and set an alert when p95 reasoning tokens or failed-unit spend exceeds the approved baseline. Then document the mapping and re-run the sample after any model or gateway change.

When the ledger is ready, Start with CometAPI and carry the same route, usage, and pricing fields into the approval packet.