CometAPI pricing reconciliation runbook

Last reviewed: 2026-05-10

Who this is for: engineering, FinOps, and platform operators who need to reconcile CometAPI usage against internal application logs, price assumptions, and billing exports before approving spend.

For broader cost-control context, see the AI cost controls home and the site’s posts archive.

Key takeaways

• Treat CometAPI pricing reconciliation as a controlled accounting process, not a one-time invoice review.
• Keep a dated price snapshot for every billing period you reconcile.
• Reconcile at three levels: request logs, provider/API usage records, and billing or invoice totals.
• Do not assume endpoint paths, auth headers, usage fields, or billing rounding rules until your team verifies them against the current CometAPI documentation and your own account data.
• Flag mismatches by category: missing requests, duplicate requests, model-name drift, token-count differences, retry amplification, currency/tax differences, and unsupported internal assumptions.

Concise definition

Pricing reconciliation is the process of comparing what your application believes it used, what the API provider reports, and what the billing system charges. For CometAPI, that means preserving request-level evidence, model and token data, dated pricing assumptions, and any billing artifacts needed to explain the final charge.

Why this matters in production

A cost dashboard can look correct while the bill is still wrong for operational reasons:

• retries may multiply billable requests;
• fallback chains may charge a different model than the primary model;
• model aliases may change or resolve differently than your internal label;
• streaming requests may be logged without final token counts;
• failed requests may or may not be billable depending on actual provider behavior;
• currency, tax, discounts, credits, and minimum charges may be applied outside the request path.

The CometAPI documentation landing page is the starting point for API reference checks, while the pricing page is the starting point for pricing-policy review: CometAPI API documentation and CometAPI pricing information. If there is ambiguity, use the CometAPI help center as the escalation path and retain the support answer with your reconciliation packet.

Production validation checklist

1. Freeze the reconciliation period

Choose the exact interval before pulling records.

Recommended fields:

• UTC start timestamp;
• UTC end timestamp;
• account or workspace identifier;
• application environment;
• model set included;
• currency expected;
• invoice or statement identifier, if available.

Validation steps:

1. Confirm all systems use the same timezone, preferably UTC.
2. Exclude partial current-day records unless your billing export supports finalized intraday data.
3. Store the period definition with the reconciliation output.
4. Keep raw exports immutable after the reconciliation run starts.

2. Capture a dated price snapshot

Before calculating costs, save the pricing assumptions used for the period.

Minimum snapshot fields:

• source URL;
• access date;
• model or SKU name;
• input-unit price;
• output-unit price;
• unit basis, such as per-token, per-1K-token, or per-1M-token;
• currency;
• notes for credits, discounts, taxes, or special account terms;
• person or job that captured the snapshot.

Source to check: the CometAPI pricing page at https://apidoc.cometapi.com/about-pricing-873788m0.

Validation steps:

1. Compare the visible pricing page to your account contract or dashboard, if you have account-specific terms.
2. Record whether prices are public-list, negotiated, promotional, or credit-adjusted.
3. Do not overwrite prior snapshots when pricing changes.
4. If your application uses model aliases, record the resolved billable model name separately.

3. Reconcile request counts before costs

Cost reconciliation should not begin until request counts are understood.

Compare:

Validation steps:

1. Select a sample of request IDs from application logs and trace them through gateway logs.
2. Identify retry behavior separately from first-attempt traffic.
3. Split successful, failed, timed-out, and canceled requests.
4. Confirm whether your cost ledger includes only final responses or all attempts.
5. Document whether failed or partial requests are billable based on verified CometAPI behavior, not assumptions.

4. Reconcile token quantities

For chat and generation workloads, token differences are often the main source of cost drift.

Track these fields per request where available:

• request ID;
• timestamp;
• model requested;
• billable model reported;
• input tokens;
• output tokens;
• cached-input tokens, if applicable and supported;
• reasoning or auxiliary tokens, if applicable and supported;
• total tokens;
• response status;
• retry attempt number;
• tenant, project, or cost center.

Validation steps:

1. Compare token totals from your app logs with provider-reported usage fields.
2. For streaming responses, confirm final usage data is captured after stream completion.
3. For timeouts, record whether your client stopped reading before final usage was returned.
4. For fallback flows, allocate usage to the model that actually served the request.
5. For prompt templates, version the template so token spikes can be explained later.

5. Validate model mapping

A reconciliation run should fail closed if the model name cannot be priced.

Create a model mapping table:

Validation steps:

1. Reject rows with blank or unknown model names.
2. Alert if a new model appears without a price mapping.
3. Separate primary and fallback traffic.
4. Keep retired model mappings for historical invoice periods.

6. Calculate expected cost with explainable rounding

Your cost calculator should produce an auditable line-level result.

Recommended calculation columns:

• input quantity;
• output quantity;
• input unit price;
• output unit price;
• unit divisor;
• subtotal before credits;
• credits or discounts;
• tax or non-usage adjustments;
• final expected total;
• rounding method.

Example formula pattern:

expected_cost = (input_tokens / unit_divisor * input_price) + (output_tokens / unit_divisor * output_price)

Use this only after confirming the actual unit basis and pricing terms from the CometAPI pricing source and your account terms.

Validation steps:

1. Run the calculator on a known small sample before the full period.
2. Compare line-level subtotals and aggregate totals.
3. Use decimal arithmetic, not binary floating point, for money.
4. Keep pre-rounding and post-rounding totals.
5. Define an investigation threshold as an internal control, not a universal truth. For example, your team might investigate any model-level variance above 1% or any absolute variance above a chosen finance threshold.

Sanitized reconciliation input example

Use a structure like this for an internal reconciliation job. Replace all placeholder values with verified data from your logs, pricing snapshot, and billing export.

{ “reconciliation_period”: { “start_utc”: “2026-05-01T00:00:00Z”, “end_utc”: “2026-05-02T00:00:00Z”, “account_ref”: “acct_redacted”, “currency”: “USD” }, “pricing_snapshot”: { “source_url”: “https://apidoc.cometapi.com/about-pricing-873788m0", “accessed_at”: “2026-05-10”, “unit_basis”: “VERIFY_FROM_SOURCE”, “prices”: [ { “billable_model”: “model_name_redacted”, “input_price”: “VERIFY”, “output_price”: “VERIFY”, “unit_divisor”: “VERIFY” } ] }, “usage_rows”: [ { “request_id”: “req_redacted_001”, “timestamp_utc”: “2026-05-01T12:34:56Z”, “internal_service”: “customer-support-chat”, “requested_model”: “model_alias_redacted”, “billable_model”: “model_name_redacted”, “status”: “success”, “attempt”: 1, “input_tokens”: 1234, “output_tokens”: 321, “cost_center”: “support” } ], “controls”: { “fail_on_unknown_model”: true, “fail_on_missing_token_usage”: true, “variance_threshold_example_percent”: 1.0, “variance_threshold_note”: “Tune to your finance policy; not a CometAPI guarantee.” } }

Contract details to verify

Do not ship a reconciliation control that depends on undocumented behavior. Verify each item against the current CometAPI docs, account dashboard, billing export, or support response.

Reconciliation workflow

Step 1: Build the evidence packet

For every billing period, store:

• raw application logs or query reference;
• gateway/proxy logs;
• CometAPI usage export or equivalent account data;
• invoice, statement, or billing screenshot/export;
• dated pricing snapshot;
• model mapping table;
• reconciliation script version;
• known exclusions;
• support tickets or help-center answers.

Keep this packet in a location finance and engineering can both access.

Step 2: Normalize rows

Normalize every usage row into a common schema:

Step 3: Run variance checks by category

Do not only compare the grand total. Break variance into explainable groups.

Recommended checks:

1. Count variance: app requests vs provider/billing requests.
2. Token variance: app token estimates vs provider-reported usage.
3. Model variance: requested model vs billable model.
4. Retry variance: first attempts vs all attempts.
5. Fallback variance: primary model vs fallback model cost.
6. Adjustment variance: credits, discounts, tax, currency, and rounding.
7. Freshness variance: late usage records not yet visible in billing.

Step 4: Decide pass, warn, or fail

Example control policy to tune:

The thresholds above are examples. Set them according to your risk tolerance, traffic volume, and finance policy.

Practical validation tests before first use

Run these tests in a non-production or low-risk environment before relying on the reconciliation job.

Test A: Known prompt, known response

1. Send one request with a fixed prompt.
2. Capture application log, gateway log, API response, and billing/usage record.
3. Confirm the same request can be joined across all systems.
4. Confirm the billable model and token fields are populated as expected.

Test B: Streaming response

1. Send a streaming request if your application uses streaming.
2. Confirm final usage fields are available and captured.
3. Simulate client disconnect if safe to do so.
4. Document whether partial streams appear in billing data.

Test C: Retry after timeout

1. Force a client-side timeout in a controlled test.
2. Observe whether your client retries.
3. Confirm whether one or multiple provider-side records exist.
4. Mark the retry policy in the reconciliation packet.

Test D: Fallback model

1. Trigger fallback using a safe controlled condition.
2. Confirm internal logs show both primary failure and fallback success.
3. Confirm cost is allocated to the model that actually served the response.
4. Verify the fallback model has a price mapping.

Test E: Unknown model guardrail

1. Add a fake model name to a test usage row.
2. Confirm the reconciliation job fails or quarantines the row.
3. Confirm finance cannot approve a period with unpriced usage.

Operational cadence

Suggested cadence for production teams:

If you maintain editorial or policy notes for your team, link the runbook from your editorial page so reviewers understand how cost-control articles and operational guidance are maintained.

Common failure modes

Missing final usage for streaming

Symptom: application logs show the request, but token totals are blank.

Likely causes:

• stream ended before final metadata was read;
• logging middleware records only the first chunk;
• client timeout interrupted the response;
• provider usage fields are in a different event than expected.

Control:

• log stream completion separately;
• require final usage fields before marking a row as reconciled;
• quarantine rows where usage is unknown.

Model alias drift

Symptom: internal service says it used one model, while billing data shows another.

Likely causes:

• alias resolution;
• fallback behavior;
• application config drift;
• provider-side model naming difference.

Control:

• store requested and billable names separately;
• map aliases explicitly;
• alert on new billable model names.

Retry amplification

Symptom: invoice volume is higher than business transaction volume.

Likely causes:

• automatic retry middleware;
• gateway retries plus application retries;
• timeout settings shorter than model response latency;
• fallback call counted in addition to failed primary call.

Control:

• include attempt number;
• log retry reason;
• cap retries by workload;
• report cost per business transaction and cost per API attempt separately.

Credits and taxes outside usage exports

Symptom: request-level expected cost matches usage subtotal but not invoice total.

Likely causes:

• account credits;
• promotional discounts;
• taxes;
• currency conversion;
• invoice-level adjustments.

Control:

• reconcile usage subtotal and invoice total separately;
• keep finance adjustments as separate rows;
• do not force request-level usage to absorb invoice-level adjustments.

FAQ

Should the invoice total exactly match request-level calculated cost?

Not always. Request-level cost usually explains usage subtotal. Invoice totals may include credits, discounts, taxes, currency conversion, rounding, or non-usage adjustments. Verify those details in your account billing data and, if needed, through the CometAPI help center.

Can I rely on today’s public pricing page for last month’s bill?

Only if you have evidence that the price did not change or you captured a dated snapshot during the billing period. For auditability, keep your own historical pricing snapshots.

What should happen when a usage row has no model mapping?

Fail or quarantine the row. A row without a verified billable model cannot be priced safely.

Should failed requests be included?

Include them in the reconciliation dataset, then classify them according to verified billing behavior. Do not assume all failed requests are free or billable without evidence.

How should fallback traffic be allocated?

Allocate cost to the model that actually served the request, while also preserving the original primary-model attempt. This lets operators see whether reliability controls are increasing spend.

What variance threshold should we use?

Set thresholds based on your finance policy and spend volume. A small percentage may still be material for high-volume workloads, while a larger percentage may be acceptable for low-volume experiments. Treat any threshold in this runbook as an example to tune.

Sources checked