Usage and cost records: reading what each request cost
Modelflare records token usage and cost for every request. This guide covers where those records live, how billing units differ between text, image, and video, the cache hit guarantee, and how long logs are kept.
Modelflare records token usage and cost per request and shows them in the console. Live prices are published on Models & Pricing; the documentation does not maintain a second price list. This article explains how to read a charge, which billing units apply to each model type, and which platform features change what a request costs.
Where charges are recorded
Every request writes an entry to the usage log in the console. When a charge needs explaining, check three things:
- The model ID. The exact ID and the quality or size parameters in the request, not a nearby variant.
- The routing group. Group multipliers apply to ordinary chat routing. Some image contracts ignore them and bill the requested quality and dimensions instead.
- The usage log. Review the entry in the console after the request completes.
When a request moves to a fallback group, or a Smart API Key resolves a group, the request is billed at the multiplier of the group that served it. The consume log records that group, and for Smart API Keys also the routing strategy.
Billing units
Language models such as GPT, Claude, and Grok are billed per million tokens, with separate input and output rates. The full pricing page lists cache, long-context, and other conditions.
Image and video model pages name their billing unit: per token, per image, per call, or per second. Use the unit on the model page together with the live price, not a generic chat-token formula. For example, the documentation lists gpt-image-2 and seedance-2.5 as per-token, wan2.7-image as per-call, seedream-5-0-lite-260128 as per-image, and the Kling and Wan video models as per-second.
Cache hit guarantee
Prompt caching lowers the price of repeated input tokens, but the hit rate depends on the provider route rather than on the client. Three OpenAI routing groups carry a published minimum daily cache hit rate:
| Group | Daily target |
|---|---|
openai-award |
65% |
openai-stable |
75% |
openai-premium |
85% |
If the measured rate for a UTC day stays below the target, the tokens missing from the target are credited back at the price difference between a cache miss and a cache read.
To make requests eligible, send prompt_cache_key on the request (Chat Completions and Responses both accept it), keep a stable prefix for that key, and use one of the groups above. Only ordinary text input counts; requests that bill image tokens, audio tokens, or cache writes are excluded. A series (one account, one prompt_cache_key, one model) starts counting only after at least one real cache read, and its eligible input is capped at the largest prefix actually read from cache in that series.
Eligible requests accumulate within a UTC day. Calculation for the previous day starts at 00:10 UTC, and the credit lands in your balance and in the remaining quota of the key that made the requests. The Cache Hit Guarantee card in Usage shows the target, the measured rate, and the amount credited per group. Only a keyed hash of prompt_cache_key is stored with the usage evidence.
Log retention
Consume and error entries are kept for the site retention period and then deleted permanently by a daily cleanup at 04:00 server time. In Profile, under Log retention, you can follow the site default or choose 7, 30, 60, 180, or 365 days for your own logs. You cannot choose a period longer than the site limit. Shortening the period asks for confirmation, takes effect on the next daily run, and cannot be undone for rows that are already deleted.
A monthly summary entry stays in the log list for every cleaned month, so historical request counts, tokens, and spend remain available. Top-up, refund, redemption, account, and system records sit outside the retention policy.
Failure diagnostics
When a request fails terminally, or a channel attempt fails before a fallback recovers it, the gateway stores one copy of the original request JSON for incident diagnosis and deletes it after 72 hours. A request that succeeds without a failed attempt is never stored this way. The copy never includes the Authorization header or any provider credential, and it is not exposed through the log APIs.
Further reading
The documentation pages Usage and cost, Cache hit guarantee, and Data retention cover each topic in full. The main site also has articles on AI API cost tracking and API key security. For volume pricing, contact business@modelflare.dev.