Skip to main content

​
Client API Usage and Billing

OMNI Client API is designed to support usage-based billing with Stripe-grade trust posture:
  • Bill only successful operations (2xx/3xx)
  • Do not bill failures (4xx/5xx)
  • Do not intentionally double-bill cached idempotency replays (for endpoints that support idempotency)
This page documents the current internal beta behavior and the control plane endpoints you can use to audit usage.

​
Billable unit

  • 1 billable unit per successful API call.
  • Successful means HTTP 2xx or 3xx.
Applies to:
  • REST /v1/* routes
  • Legacy MCP compatibility routes (/v1/mcp/*)
  • Hosted MCP JSON-RPC methods (tools/list, tools/call) over POST /mcp

​
Idempotency and billing

Idempotency is required for tool execution:
  • POST /v1/mcp/invoke
  • tools/call over POST /mcp
Billing rules:
  • A successful first attempt is billable.
  • If an idempotent retry returns a cached replay response, it is not billed again.
  • For read-only calls (GET and hosted tools/list), each successful HTTP response is billable. Retries can be billed more than once if multiple attempts succeed.

​
Internal beta billing mode

Internal beta runs in a production-like mode:
  • live Stripe meter event emission
  • parallel shadow ledger for reconciliation
This is intentionally stricter than “fake billing” so metering issues are found before public beta.

​
Control plane endpoints (internal beta)

During internal beta, usage and billing insights are exposed via the OMNI control plane. These endpoints require an OMNI user session token (not an OMNI Client API key): 
Authorization: Bearer <omni_user_jwt>
Base URL: 
https://omni-mcp.fly.dev/api/client

​
Billing summary

GET /billing
Includes:
  • current per-call price
  • billable units this month (shadow ledger)
  • estimated spend
  • spend cap and remaining headroom (if configured)

​
Usage breakdown

GET /usage?days=30
Returns totals and breakdown by endpoint.

​
Reconciliation dashboard

GET /reconciliation?days=30
Compares:
  • shadow-ledger billable units
  • Stripe-recorded units (based on successful meter-event emission)

​
Pause and resume billing traffic

POST /billing/pause
POST /billing/resume

​
Set spend cap (hard limit)

POST /billing/cap
Body: 
{ "spendCapUsd": 25 }
If your spend cap is exceeded, the control plane will reject resuming until you increase the cap.

​
Operational guidance

​
Monitor drift early

During internal beta, reconciliation drift can happen due to transient Stripe meter-event failures. Recommended posture:
  1. Check /reconciliation daily.
  2. Treat drift as a bug until proven benign.
  3. If drift persists, pause billing traffic and investigate with request IDs.

​
Use request IDs everywhere

For every call:
  • provide X-Request-Id (optional but recommended)
  • always log error.request_id (on failures)
This gives you a stable join key across:
  • your logs
  • OMNI support investigations
  • usage ledger rows