Pricing Reference

For: Platform operators and developers who need to understand how cost_usd is computed per request, and how budget caps and monthly limits are enforced.

Table of Contents

• Per-Model Rates
  • OpenAI
  • Anthropic
  • Default (unknown models)
• How cost_usd is Computed
  • Request-time estimate
  • Final cost after response
• Budget Enforcement
  • Per-request cap
  • Monthly org limit
  • Per-project budget cap
• Usage Reporting
• See also

Per-Model Rates

Rates are in USD per 1,000,000 tokens (per-million). The gateway uses these rates to compute the cost_estimate_usd at request time and the final cost_usd when the response arrives.

OpenAI

Anthropic

Default (unknown models)

When the model name is not in the table above, the gateway uses a conservative fallback rate:

This covers Google Gemini, Azure OpenAI, Cohere, and any other provider whose model is not explicitly listed. Rates are updated as new models are added.

Monetary precision: All cost values are stored and computed as exact decimal strings (e.g. "0.003750"), never floating-point. The gateway uses the shopspring/decimal library for all arithmetic.

How cost_usd is Computed

Request-time estimate

When the gateway receives a request, it computes a cost_estimate_usd immediately, before sending the request upstream. This estimate is used for pre-execution budget enforcement (the budget.usd_max policy field):

cost_estimate_usd = (tokens_in × rate_in + tokens_out_max × rate_out) / 1,000,000

Where:

• tokens_in — token count from the inbound request (computed from action.params.messages via the provider's tokenizer approximation, or from estimates.tokens_in in the policy DSL)
• tokens_out_max — the max_tokens field in action.params, or the DSL estimates.tokens_out_max override; if neither is set, a conservative default is used
• rate_in / rate_out — per-million rates from the table above

Final cost after response

When the upstream provider returns, the actual token counts in the response body are used to compute the final cost_usd stored in the execution record:

cost_usd = (actual_tokens_in × rate_in + actual_tokens_out × rate_out) / 1,000,000

The final cost_usd is what appears in GET /v1/records/{record_id} and in usage reports. The estimate is only used for pre-execution policy checks.

Example:

A request to gpt-4o-mini with 500 input tokens and max_tokens: 200:

estimate = (500 × 0.15 + 200 × 0.60) / 1,000,000
         = (75 + 120) / 1,000,000
         = 0.000195 USD

If the model returns 87 actual output tokens:

final = (500 × 0.15 + 87 × 0.60) / 1,000,000
      = (75 + 52.2) / 1,000,000
      = 0.0001272 USD

Budget Enforcement

Per-request cap

The policy DSL budget.usd_max field enforces a per-request cost ceiling. If the estimated cost exceeds the cap, the request is denied before it reaches the upstream provider:

# In budgets.yaml
- conditions:
    workload.workload_id:
      equals: wl-my-app
  effect:
    decision: allow
    budget:
      usd_max: "0.05"   # deny any single request estimated > $0.05

Response on denial:

{
  "decision": "deny",
  "reason": "budget_exceeded",
  "decision_trace": {
    "reason_codes": ["budget_usd_max_exceeded"],
    "attributes": {
      "cost_estimate_usd": "0.0612",
      "budget_usd_max": "0.05"
    }
  }
}

Monthly org limit

Each organization can have a monthly_request_limit set in the org_plans table. When the limit is reached:

• If overage_enabled = false (default): the gateway returns HTTP 403 with reason: "monthly_request_limit_exceeded".
• If overage_enabled = true: requests continue and overage usage is tracked separately for billing.

Monthly counts reset at the start of each calendar month (UTC). Current usage is visible at GET /v1/reports/usage.

Per-project budget cap

The policy DSL also supports monthly spend caps keyed by project_id:

- conditions:
    attribution.project_id:
      equals: proj-chatbot
  effect:
    decision: allow
    budget:
      monthly_usd_max: "50.00"   # deny when project spend > $50 this month

When the project cap is reached, the gateway returns HTTP 403. The count resets monthly.

Usage Reporting

Org-level usage (API key auth)

Aggregate usage and spend data is available via the reporting endpoints:

# Monthly token and request counts by workload
curl -s "$GATEWAY_URL/v1/reports/usage" \
  -H "Authorization: Bearer $API_KEY" | jq .

# Monthly spend by provider (based on final cost_usd)
curl -s "$GATEWAY_URL/v1/reports/spend" \
  -H "Authorization: Bearer $API_KEY" | jq .

Both endpoints return data for the org associated with the API key.

Admin billing summary (admin token auth)

Platform operators can query the full billing breakdown across all orgs and workloads using the admin billing endpoints:

# Billing summary for the current month (grouped by workload → connector)
curl -s "$GATEWAY_URL/v1/admin/billing/summary" \
  -H "MVGC-Admin-Token: $ADMIN_TOKEN" | jq .

# Filter by month
curl -s "$GATEWAY_URL/v1/admin/billing/summary?period=2026-03" \
  -H "MVGC-Admin-Token: $ADMIN_TOKEN" | jq .

# Export as CSV (for spreadsheets or BI tools)
curl -s "$GATEWAY_URL/v1/admin/billing/export.csv?period=2026-03" \
  -H "MVGC-Admin-Token: $ADMIN_TOKEN" -o billing-2026-03.csv

Summary response fields:

CSV columns: period, org_id, workload_id, connector_id, request_count, tokens_in, tokens_out, cost_usd

Monetary precision: All cost totals use exact integer arithmetic on the 8-decimal-place fixed-point strings. No floating-point accumulation is performed at the API layer.

See also

• Budget enforcement in policy DSL
• Usage reporting
• Glossary — cost_usd
• FAQ — billing and limits