API Billing Mismatch Checklist

Define the Billing Mismatch

Before investigating, identify which three numbers are in disagreement:

• Local estimated cost — your calculation based on local logs, token counts and known unit prices
• Provider-reported usage cost — the per-request or per-period cost shown in the API response, usage endpoint or activity dashboard
• Account or invoice total — the balance change, credit deduction or period invoice amount

Do not assume these three numbers should naturally match. They can differ because local estimates use different rates, omit billable fields, or use a different time window.

unexplained_difference = provider_reported_total - locally_reconstructed_total

Use this remainder as the actual investigation target. A small unexplained difference is normal; a large one warrants deeper review.

Gather Evidence Before Recalculating

Do not delete or overwrite logs during an investigation. Collect all of the following before recalculating:

• ✓request_id for every API call
• ✓session_id or job_id if the platform uses them
• ✓timestamp in UTC with timezone offset
• ✓Provider and model used
• ✓Provider route, if visible in the response
• ✓HTTP status code and error body
• ✓Success or failure state
• ✓tokens_in and tokens_out
• ✓Cached input tokens, if reported
• ✓Reasoning tokens, if applicable
• ✓tool_calls count and type
• ✓For image APIs: count, resolution and operation type
• ✓For video APIs: duration, resolution and frame rate
• ✓retry_count for the request
• ✓Local estimated cost per request
• ✓Provider-reported cost from the response or dashboard
• ✓Dashboard or invoice record for the period

Normalize the Time Window and Time Zone

Before comparing any totals, convert both datasets to the same time zone and use the same inclusive start and exclusive end timestamps.

• Local logs may default to UTC; the provider dashboard may display account local time
• Daily totals may be cut off at different hours depending on the provider's day boundary
• Pending or batched usage may appear in the dashboard after the request completed
• Credit purchase timestamps may be recorded in a different timezone than usage deductions
• Export the exact start and end timestamps from both systems before summing

Do not compare a 24-hour local log against a calendar-day dashboard total without verifying the time boundaries match.

Reconcile Request Counts

Count the following in both local logs and provider activity separately:

• Local application request count
• Provider activity request count
• Successful request count (both sources)
• Failed request count (both sources)
• Automatic retry count
• Duplicate request count

Sources of extra provider-side requests include:

• SDK automatic retries
• Proxy-layer retries
• Application-level retries after a timeout
• Webhook retries on delivery failure
• Duplicate queue deliveries
• Frontend double-submit on slow responses
• Parallel workers that each sent the same prompt independently
• Fallback attempts to an alternative model or provider
• Retries after a rate-limit response

Retries and fallback attempts can change request counts, but their billing treatment depends on the provider and response outcome. Inspect the actual usage record instead of assuming every attempt was charged.

Reconcile Billable Units

Text and Agent Requests

Possible billable fields that may not all be in a local estimator:

• Input tokens
• Output tokens
• Cached input tokens (discounted or free on some providers)
• Cache write tokens
• Reasoning tokens (charged on some reasoning models)
• Repeated conversation history sent on each turn
• Tool definitions and schema
• Tool results returned to the model
• Retrieved context from RAG or memory systems

Identify the specific token fields missing from your local estimator rather than using vague labels. Look for the exact billable field name in the provider response and add it to your calculation.

Image Requests

• Input image count and resolution
• Output image count
• Resolution tier (some providers bill by megapixel bucket)
• Editing, upscaling or variation operations
• Per-image pricing vs. tokenized image pricing

Megapixels are an estimation input, not a universal billing unit. Check the provider's actual billing unit.

Video Requests

• Duration in seconds
• Resolution tier
• Frame rate
• Number of outputs per request
• Extension or upscaling operations
• Successful vs. usable output count (failed generations may or may not be billed)

Check Model and Provider Routing

Your local estimate must match the model and provider that actually handled the request:

• A model alias may resolve to a different model version with different pricing
• A gateway or proxy may route to a different underlying provider
• A fallback model may be charged at a different rate than the requested model
• Some providers charge differently for the same model depending on the deployment type

Record these fields for each request to make routing comparison possible:

• requested_model
• resolved_model — from the API response
• provider_route — if exposed in the response
• pricing_snapshot_date — when you recorded the rate used for local estimation

Do not assume a route change occurred without usage evidence. Some providers show the resolved model in the response body or activity log.

Check Retries, Fallbacks and Duplicate Requests

Retries and fallback attempts affect cost in ways that simple request counting misses:

• A retriable error may generate multiple provider-side requests for one application request
• Each retry attempt may consume tokens and cost credit
• A fallback to a cheaper model reduces per-request cost; a fallback to a more expensive one increases it
• A timeout that triggers a client-side retry without a server-side attempt costs nothing
• A failed streaming response that partially generated tokens may still report partial usage

For each request with a high retry_count, check whether the provider activity log shows multiple entries with the same or similar prompt.

Check Cached, Reasoning and Tool-Use Tokens

Some providers report billable token categories that are not always captured in a basic local estimator:

• Cached input — some providers bill cached input at a discount; others bill it at zero
• Cache writes — some providers charge for cache creation
• Reasoning tokens — some reasoning models charge reasoning separately from input/output
• Tool-call tokens — tool definitions and results can add significant input token overhead in agent workflows

Compare each reported token category from the provider against the fields your local estimator uses. Look for categories in the response that are not in your calculation.

Check Image and Video Billing Units

Media APIs often use billing units that differ from per-token text pricing:

• Billed per output image vs. per megapixel vs. per token — these give different totals
• Number of images per generation call may differ from the number you counted
• Video generation may bill per second or per frame, not per operation
• Failed or timed-out generations may or may not appear in the usage log depending on the provider
• Webhook delivery failures may trigger retries with additional cost

Verify the Price and Effective Date

Use the rate that was active at the time of the request, not today's rate:

• Record the pricing snapshot date alongside each local estimate
• Check whether the provider publishes historical pricing or only current pricing
• Distinguish between input token, output token, cache, batch and media operation rates
• Do not recalculate historical charges using a rate that changed after the billing period
• Provider price changes may not be announced in advance — check the effective date in the activity log

Failed, Timed-Out and Partial Requests

Billing treatment for failed, timed-out, cancelled or partially streamed requests varies by provider and failure stage. Check the HTTP response, returned usage data, request ID, activity record and current provider documentation before counting or excluding the request.

Do not assume all failed requests are free, or that all are charged. The correct approach is to inspect the specific response and activity log entry.

Prepaid Credits vs Usage Charges

In prepaid systems, several different balance movements can occur:

• Credit purchase — adds to the balance; not a usage charge
• Usage deduction — the cost of API calls; what you are investigating
• Bonus or promotional credit — may expire or have different terms
• Refund or adjustment — may appear separately from usage
• API-key spending limit — may cap usage independently of the account balance

Do not treat a credit purchase as a usage charge, or a balance change as equivalent to a per-request billed cost. Check which transactions are usage and which are funding.

Worked Reconciliation Example

A real investigation typically follows this pattern:

Next steps for the remaining $0.15:

• Check for rounding in per-request costs
• Identify one unmatched request ID in the provider log
• Check whether a cached token field was omitted from the local calculation
• Verify no rate version mismatch occurred mid-batch
• Confirm the 4 retries produced 4 extra provider records at $0.0375 each

Do not assume the unexplained remainder is always one specific cause. Use evidence to narrow it down.

Investigation Checklist

• ✓Freeze the investigation time range — note exact start and end timestamps
• ✓Export all local request logs for the period
• ✓Export provider usage records from the activity or billing dashboard
• ✓Normalize timestamps to the same timezone in both datasets
• ✓Match request_id values between local logs and provider records
• ✓Compare request counts (local vs. provider activity log)
• ✓Compare billable units per request (tokens, images, video duration)
• ✓Identify retries, duplicates and fallback attempts
• ✓Verify model and provider_route against local estimation rate
• ✓Apply the correct historical rates for each request date
• ✓Separate credit purchases and adjustments from usage charges
• ✓Calculate the unexplained remainder
• ✓Escalate to support only with evidence — do not send API keys

Support Escalation Package

When escalating to provider support, include only the following:

• Account or organization ID (not a secret)
• request_id values for the affected calls
• Timestamps and timezone used
• Model and provider route for each affected request
• HTTP status code and error code or type
• Local usage calculation showing the per-request estimate
• Provider usage record from the dashboard or API response
• Dashboard screenshot with any sensitive data redacted
• The exact unexplained amount and how it was calculated
• Concise reproduction steps

Do not send:

• API key or management key
• Authorization header
• Full logs containing secrets or other users' data
• Customer private data unrelated to the billing question

Related Guides

Frequently Asked Questions