Research-backed calculator guide

Structured Output Schema Overhead Calculator: Price the Token Tax per Call

Estimate the incremental input, output, retry, and monthly cost created by JSON Schema structured outputs, with transparent assumptions and a worked example.

schema tax per call =
  (schema input tokens × uncached input rate)
+ (schema input tokens × cached-input rate, if that portion is cached)
+ (extra output-format tokens × output rate)
+ (expected repair attempts × full repair-call cost)

The schema itself is only one part of the calculation. OpenAI describes Structured Outputs as a way to make a response adhere to a supplied JSON Schema, and exposes it through response formatting or function calling. ^[1] Anthropic’s documentation is unusually explicit that structured outputs can add an automatic system prompt and that changing the format can affect prompt-cache behavior. ^[3] Google likewise documents JSON Schema as part of the response format. ^[4] Those mechanics are why the right question is not “does JSON Schema cost extra?” but “how many billable input and output tokens did this request actually use?”

For a concrete illustration, assume 2,000,000 calls per month, a 220-token baseline prompt, a 340-token schema, 180 visible output tokens, 35 extra JSON-format tokens, a 4% repair rate, and illustrative rates of $0.10 per 1M uncached input tokens and $0.50 per 1M output tokens. The schema adds $68 per month, output formatting adds $35, and expected repairs add $13.08. The total incremental tax is $116.08 per month under those assumptions. Those rates are an example, not a quote for every model or provider.

What the calculator measures

The calculator is designed for structured extraction, classification, routing, and tool-adjacent calls where a schema is attached to every request. Start with the request that would have been sent without structured output. Count the model-facing input tokens, not just the characters in the user’s message. Include system or developer instructions, conversation history, retrieved text, tool definitions, and any other content sent with the request.

Then run the same workload with the schema enabled. The difference in reported input tokens is your measured schema-side delta. This may include more than the literal JSON text. A provider can transform a schema, inject instructions, or represent it through an internal constrained-decoding mechanism. Anthropic says its structured-output flow adds a system prompt explaining the expected format and that the injected prompt is billed like other input. ^[3] That is a provider-specific documented behavior, not a universal rule.

Track output separately. A compact JSON object may use fewer tokens than pretty-printed JSON, while field names, quotes, braces, repeated array objects, and explanatory string values can add output tokens. Do not infer output tokens from word count. Use the usage object returned by the API or the provider’s usage export. OpenAI’s text-generation documentation notes that a response can contain text, tool calls, reasoning items, and other output items, so a visible text count is not a complete usage ledger. ^[1]

Finally, model failures. If a validator rejects a response and you send a repair prompt, the repair attempt is another priced request. If the repair repeats the full schema and context, its cost can approach the original structured call. If your retry sends only a concise error and the failed value, use that smaller measured call instead of assuming a full duplicate.

Inputs to collect before pricing

Record these inputs for one representative call and for a billing period:

1. Baseline input tokens: the same request without the schema or structured-output option.
2. Structured input tokens: the usage-reported input after enabling the schema.
3. Schema delta: structured input minus baseline input. If the result is negative, keep the observed result and investigate prompt or caching changes rather than forcing a positive tax.
4. Baseline output tokens: output tokens for the control request.
5. Structured output tokens: output tokens with the schema enabled.
6. Repair probability: failed structured calls divided by completed structured calls over the same workload slice.
7. Repair-call tokens: measured input and output for a typical repair, including whether the schema is resent.
8. Rates and units: input, cached-input, and output prices in dollars per million tokens, or the provider’s actual billing unit.
9. Volume: calls per day or month. Keep batch, priority, regional, and other service tiers separate when their prices differ.

OpenAI’s pricing page lists separate input, cached-input, and output categories and notes that listed rates can depend on processing mode and context length. ^[2] It also describes a Batch API discount. Do not silently apply that discount to interactive traffic. Record the mode and effective date with the rate card. This draft uses the OpenAI page checked on 2026-11-02 as a dated reference, while the worked example below deliberately uses clearly labeled illustrative rates rather than presenting them as a universal quote.

Worked cost example

Assume a short classification workload. The control request contains 220 input tokens and produces 180 output tokens. The structured version adds 340 input tokens for the schema and surrounding format handling, plus 35 output tokens of JSON syntax. Suppose 4% of structured calls need one repair. For a simple first-pass estimate, assume the repair is a full structured call with the same token profile. Use $0.10 per 1M uncached input tokens and $0.50 per 1M output tokens. These prices and the 4% repair rate are assumptions for this example, not vendor quotes or a forecast.

The same result can be split into decisions. The schema input component is $68 per month. The extra output-format component is $35 per month. The expected repair component is $13.08 per month. The baseline workload costs $224 per month under these rates, while the structured version costs $327 per month before repairs and $340.08 per month after the expected repair calls. The structured-output tax is therefore $116.08 compared with the control, not $340.08 in total spend.

If the provider recognizes a cached portion of the schema or stable instruction prefix, replace the uncached input rate for that portion with the cached-input rate. For example, with 200 of the 340 schema tokens cached, the schema component becomes (140 × uncached input rate) + (200 × cached-input rate). Do not subtract cached tokens twice. They remain part of the model context even when the billing category is cheaper.

How to measure the real schema delta

Create a small paired test set that represents production traffic. Keep the model, input text, system instructions, temperature or equivalent controls, and service tier fixed. Send each item once in control mode and once with the schema. A single prompt can mislead because tokenizers may split punctuation and field names differently, and output length is variable.

For each pair, store baseline input, structured input, baseline output, structured output, finish status, and any repair attempts. Calculate the median and p95 deltas. The median helps price ordinary calls; the p95 helps budget a workload where schemas become unusually large or outputs contain long arrays. Separate short requests from long-document requests. A fixed 340-token schema is a large percentage of a 220-token prompt but a small percentage of a 10,000-token context.

Also test schema revisions. Descriptions, examples, long enum labels, nested objects, optional branches, and repeated item schemas can all change the request shape. Anthropic documents grammar compilation and caching characteristics for structured outputs, including additional first-request latency and cache invalidation when the schema structure changes. ^[3] That latency is not automatically a token charge, but it is a useful operational exclusion: a cost worksheet should not silently convert every latency effect into dollars.

OpenAI, Anthropic, and Google expose different request shapes for structured responses. OpenAI documents response-format and function-calling forms. ^[1] Anthropic uses output_config.format for JSON Schema outputs and separately documents strict tool use. ^[3] Google’s Gemini API uses an application/json response format with a schema. ^[4] Keep provider measurements in separate rows instead of averaging their token behavior into one “JSON overhead factor.”

How to reduce the tax without hiding reliability costs

First, remove fields that downstream code never reads. A smaller schema usually reduces both schema-side input and the number of fields the model must emit. Avoid putting long examples or prose descriptions into every field unless they improve correctness enough to justify their measured cost.

Second, inspect output shape. If an array contains repeated objects, ask whether every repeated key is necessary. Do not replace JSON with a custom delimiter format solely to reduce tokens. That can move cost into parsing, escaping, validation, and incident handling. A compact format is only cheaper if its error and repair rates remain acceptable.

Third, split the control plane from the data plane. Stable schemas and stable instructions may be eligible for provider caching, but the exact cache rules differ. Measure cache hits and misses from the provider’s usage fields. Keep a schema version identifier in your cost ledger so a change can be matched to a change in input tokens, output tokens, or validation failures.

Fourth, price retries as expected value. A 1% repair rate with a full repeated context can be more expensive than a 5% repair rate with a tiny error-only correction, depending on the token sizes and output prices. Use expected repair cost = failure probability × measured repair-call cost, and report the probability by task type rather than using one global average.

For monthly planning, compare the result with the LLM cost calculator and use the AI token cost calculator when you need to separate input, output, and cached tokens. If you are comparing providers or models, the model pricing comparison can hold the rate-card assumptions while this worksheet isolates the structured-output delta.

Limits and exclusions

This method estimates token-metered API spend. It excludes application CPU, JSON parsing, schema compilation infrastructure, network transfer, storage, observability, human review, and the opportunity cost of latency unless you add those as separate rows. It also excludes provider-side fees that are not priced by input or output tokens, including any tool, search, image, audio, or platform charges.

The example assumes one repair attempt and a full-size repair call. Production retry loops may have a cap, backoff, partial context, or a fallback model. Replace the assumption with observed distributions. A schema may be accepted without an additional visible input-token delta on one provider and produce a material delta on another. The provider’s usage record and invoice remain the reconciliation source of truth.

Pricing changes over time. The example’s rates are not a promise of current or future pricing. Save the checked date, model identifier, service tier, currency, and unit next to every calculation. Never infer savings, ranking, traffic, or revenue from the size of a token delta.

FAQ

Does Structured Outputs always add a separately billed schema line item?

No. A provider may report the effect as ordinary input tokens, cached input, output tokens, or another usage category. OpenAI’s pricing page presents input, cached-input, and output categories rather than a universal schema surcharge. ^[2] Measure the usage delta between a control request and a structured request, then apply the rate category that the provider reports.

Is the literal JSON Schema character count enough to predict cost?

No. Character count is a useful diagnostic, not a billing measurement. Tokenizers split punctuation, names, descriptions, and repeated syntax differently. Providers can transform or augment a schema. Anthropic documents an injected system prompt for structured outputs, while OpenAI and Google document different API request shapes. ^{[1] [3] [4]} Use provider-reported usage for the final estimate.

Should schema tokens be counted as input or output?

A schema supplied with the request is normally modeled as input-side work, while JSON braces, keys, and values generated in the response are output-side work. The exact usage fields and provider treatment can vary. Keep the two components separate in your ledger so the correct input and output rates can be applied.

How do retries change the structured-output cost?

A retry adds its own measured input and output cost. If the retry resends the complete schema and context, it can be close to the original call. If it sends only a validation error and the failed value, it may be much smaller. Multiply the observed repair-call cost by the failure probability for the relevant task slice instead of applying a generic percentage.

Can prompt caching make the schema tax negligible?

It can reduce the price of a repeated portion when the provider’s caching rules recognize it, but caching does not remove the schema from the context. Use the provider’s cached-input usage field and rate. Anthropic also notes that changing the structured-output format can invalidate prompt-cache behavior, so version schema changes and remeasure after every material revision. ^[3]

Is a delimiter or YAML format always cheaper than JSON?

No. A different format can shorten output syntax in one workload but increase parsing failures or prompt instructions in another. The Microsoft-published experiment visible in the benchmark compares several formats, but its token counts are workload-specific. Treat the alternative as an A/B test: compare total cost per accepted result, including repairs and validation, not just nominal output tokens.