CometAPI billing caveats for cost operators

Last reviewed: 2026-05-09

Who this is for: platform, FinOps, SRE, and engineering operators who need to turn CometAPI usage into reliable budget controls, alerts, or reconciliation reports without assuming undocumented billing behavior.

This runbook is intentionally conservative. The supplied public evidence is the CometAPI Help Center at https://apidoc.cometapi.com/help-center. Treat that page, any linked CometAPI documentation, and any account-specific support response as the sources to verify before hard-coding billing, request-volume, rate-limit, or usage-field assumptions.

For broader cost-control context, keep this runbook linked from the site index at /sites/ai-cost-controls/ and maintain implementation notes under /sites/ai-cost-controls/editorial/.

Key takeaways

• Do not treat request count as spend. A request-volume chart can be useful for trend detection, but it is not a billing contract unless CometAPI documentation explicitly says how each request type is charged.
• Separate three ledgers: your client logs, CometAPI-visible usage or billing data, and finance records such as invoices, credits, or account balance exports.
• Failed requests, retries, timeouts, cancelled streams, cached responses, and partial outputs need explicit billing verification before they are included in automated cost controls.
• Keep cost guardrails local and reversible until the CometAPI Help Center or a linked official source confirms endpoint paths, fields, posting delay, and error semantics.
• Store evidence with every assumption: URL, access date, screenshot or export hash if allowed, owner, and next review date.

Concise definitions

Billing caveat: an unresolved detail that can change how usage becomes cost, such as posting delay, rounding, credits, retries, failed requests, or whether a usage field is billable or only informational.

Request-volume caveat: an unresolved detail that can change how request counts should be interpreted, such as duplicate retries, client timeouts, streaming cancellations, asynchronous processing, or dashboard aggregation windows.

Contract detail: a behavior your automation depends on, such as an endpoint path, authentication header, response field, error code, or documented rate-limit header. If it is not in official documentation or confirmed by support, treat it as unverified.

Operator runbook

1. Build an evidence register before automating

Create a small register for every billing or request-volume assumption.

Minimum fields:

• assumption name
• operational owner
• source URL or support ticket reference
• date accessed
• exact statement or screenshot reference
• system depending on the assumption
• fallback behavior if the assumption changes
• next review date

Start with the CometAPI Help Center source: https://apidoc.cometapi.com/help-center. If the help-center page links to more specific API, billing, or account documentation, cite the specific linked page in your internal register rather than relying only on the landing page.

2. Classify each usage signal

For each data source, mark whether it is one of the following:

Do not merge these signals into one “truth” table until you know which one is authoritative for each purpose.

3. Validate request volume with a controlled window

Use a low-risk project, limited tenant, or short time window. The purpose is not a generic smoke test; it is to measure how CometAPI-visible volume lines up with your own ledger.

Suggested validation steps:

1. Pick a UTC window, such as 15 minutes. Treat this threshold as an example to tune.
2. Send a small number of known requests from one service instance.
3. Attach a client-side correlation ID in your own logs. Only send it to CometAPI if an official field or header is documented for that purpose.
4. Log:
   • timestamp before send
   • timestamp after response or timeout
   • HTTP status
   • client timeout flag
   • retry attempt number
   • configured model or model alias
   • response ID if returned
   • usage fields if returned
5. After the window, compare local request count with any CometAPI-visible usage, dashboard, or export source that the Help Center or linked documentation identifies.
6. Record unmatched cases separately:
   • local timeout but later server response unknown
   • retry after 5xx
   • retry after network failure
   • cancelled stream
   • client-side validation error before calling CometAPI

4. Validate billing behavior by outcome class

For each outcome class, verify whether it is billable, non-billable, partially billable, or not stated in the official source.

Until these are confirmed, configure dashboards to show “estimated usage” rather than “final spend.”

5. Keep a dual ledger: estimate now, reconcile later

Use two separate columns in internal reporting:

• Estimated cost: generated from client logs and documented usage fields, useful for fast alerting.
• Reconciled cost: generated from CometAPI billing/account evidence or finance records after the posting window has passed.

Do not overwrite the estimate. Keep both values so operators can measure variance.

Example variance categories:

• posting delay
• retry duplication
• timeout ambiguity
• missing usage field
• billing adjustment or credit
• model alias mapped to different billable unit than expected
• dashboard window differs from application window

6. Use local guardrails before depending on provider-side limits

If you need a hard budget stop, enforce it in your own application path before sending the request. Provider-side balance, billing, or quota behavior should not be treated as a hard control unless the current CometAPI documentation explicitly supports that interpretation.

Example guardrails to tune:

• per-tenant daily estimated spend cap
• per-service request burst cap
• per-user maximum tokens or output length
• denylist for expensive model aliases until approved
• queue pause when reconciliation variance exceeds an internal threshold

These are operational examples, not universal thresholds.

Sanitized cost-ledger example

Use a normalized ledger event like this before trying to calculate final spend. Leave unknown fields as null; do not coerce unknown billing data into zero.

{
  "event_type": "ai_request_cost_observation",
  "source": "client_ledger",
  "environment": "prod",
  "provider": "cometapi",
  "tenant_id_hash": "tenant_hash_redacted",
  "request_correlation_id": "req_20260509_000123",
  "cometapi_response_id": "redacted_or_null",
  "configured_model": "model_alias_from_config",
  "started_at_utc": "2026-05-09T10:15:22Z",
  "ended_at_utc": "2026-05-09T10:15:24Z",
  "http_status": 200,
  "retry_attempt": 0,
  "client_timeout": false,
  "stream_cancelled": false,
  "usage_from_response": {
    "prompt_tokens": null,
    "completion_tokens": null,
    "total_tokens": null,
    "field_contract_verified": false
  },
  "estimated_cost": {
    "amount": null,
    "unit": "unverified",
    "pricing_source": null
  },
  "billing_reconciliation": {
    "posting_window_utc": "2026-05-09",
    "matched_in_cometapi_source": "pending",
    "variance_reason": null
  }
}

Contract details to verify

Practical validation checklist

Use this as an operating sequence, not as a one-time checklist.

1. Document the source
   Record the CometAPI help-center URL, access date, and the exact linked page or article used for each assumption.

2. Run a narrow request window
   Use a known service, known tenant, and known UTC range. Avoid running validation during deployments, incident recovery, or load tests.

3. Preserve raw local logs
   Keep request IDs, retry counts, status codes, timeout flags, and response usage fields.

4. Wait for the documented posting window
   If the official source states a delay, wait for it. If no delay is documented, mark the delay as unknown and test several observation points.

5. Compare by outcome class
   Do not compare only aggregate request totals. Break down success, 4xx, 429, 5xx, timeout, retry, and cancelled stream.

6. Record variance before changing controls
   A variance might be caused by timing, retries, aggregation, credits, or undocumented behavior. Record the reason before changing budget thresholds.

7. Review after every contract change
   Re-check assumptions when changing model aliases, authentication method, billing account, gateway, retry policy, or streaming behavior.

Operating policy for cost alerts

For near-real-time alerts, use client-side estimates with clear labels:

• “estimated request volume”
• “estimated token volume”
• “estimated spend”
• “unreconciled variance”

For finance-facing reports, use reconciled values only after the billing source has settled. If the source does not document settlement timing, state the observation time and mark the report provisional.

Recommended alert design:

FAQ

Can request count be used as a budget control?

Yes, but only as a rough early-warning signal. Request count does not necessarily equal billable usage. Token volume, output length, model selection, retries, errors, and billing adjustments can all affect cost. Use request count to detect spikes, not to close the books.

Does this runbook confirm CometAPI billing endpoint paths?

No. The supplied evidence is the CometAPI Help Center URL. This draft does not claim a specific billing, usage, invoice, or balance endpoint. Verify endpoint paths in current official documentation or through CometAPI support before automating.

Should failed requests be counted in cost estimates?

Count them in an operational ledger, but keep them separate from billable usage until the official source confirms how each failure type is treated. At minimum, separate 4xx, 429, 5xx, timeout, network failure, retry, and cancelled stream outcomes.

What should we do if client logs and CometAPI-visible usage disagree?

Do not immediately change pricing logic. First check timestamp boundaries, posting delay, retries, duplicate user actions, streaming cancellation, model alias changes, and missing response IDs. If variance remains unexplained, preserve the evidence and ask for clarification through the official support path.

Can we publish final spend from estimated token counts?

Avoid that unless the token fields, billable unit, price source, rounding behavior, and posting window are all documented and reconciled. Use “estimated spend” for operational dashboards and “reconciled spend” for finance or customer-facing reports.

How often should these assumptions be reviewed?

Review them whenever you change model configuration, retry policy, authentication, billing account, or cost-control code. Also schedule a periodic review; for active production systems, a monthly or release-based review is usually safer than waiting for a billing surprise.

Sources checked