Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clearmaas.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What you pay

ClearMaas charges you the upstream provider’s published per-token price, with no per-token markup. Revenue comes from optional paid subscription plans, not from inflating your token cost.

​
The usage object

Every chat/responses response includes a usage field: 
{
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 34,
    "total_tokens": 46
  }
}
Reasoning models add completion_tokens_details.reasoning_tokens for the hidden reasoning pass.

​
Built-in tool charges

When the response uses a built-in / server-side tool, the call is counted and billed on top of token usage. ClearMaas passes the upstream provider’s per-call rate through with no markup; refer to each provider’s pricing page for current rates. Tools that trigger per-call charges across providers:
  • OpenAI — web_search, web_search_preview, image_generation (Responses API built-in tools)
  • Anthropic — web_search (server tool)
  • Google Gemini — googleSearch grounding (per grounded prompt on Gemini 2.x family; per query on Gemini 3.x family)
  • xAI Grok — web_search, x_search, code_interpreter (Agent Tools API on /v1/responses)
Specific OpenAI rates currently passed through:
ToolPer-call rate
web_search$10 per 1,000 calls (unified across models)
web_search_preview10/1kforreasoningmodels(‘o3∗‘,‘o4∗‘,‘gpt−5∗‘);10 / 1k for reasoning models (`o3*`, `o4*`, `gpt-5*`); 25 / 1k for non-reasoning models (gpt-4o*, gpt-4.1*, etc.)
For other providers’ server-tool rates, see each provider’s official pricing page.

​
ClearMaas response headers

HeaderWhen set
X-Clear-Fallback-LevelIndex of the fallback model that served the response
X-Clear-Fallback-ModelName of the fallback model
X-Clear-RouterName of the clearmaas/{name} router used
X-Clear-Resolved-ModelConcrete model a named router resolved to
See Routing / Response Headers for use cases.

​
Looking up your usage

The Dashboard at clearmaas.com/console shows daily spend, total spend over a chosen window, and a per-model breakdown. The Dashboard does not currently break spend down per API key — costs are aggregated at the workspace level. Two OpenAI-shape billing endpoints are also exposed for programmatic access: 
# Total usage so far (returns an OpenAIUsageResponse with TotalUsage)
curl https://api.clearmaas.com/v1/dashboard/billing/usage \
  -H "Authorization: Bearer sk-clearmaas-..."

# Remaining quota and expiry (returns OpenAISubscriptionResponse)
curl https://api.clearmaas.com/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer sk-clearmaas-..."
These are summary endpoints — they don’t include OpenAI’s full historical day-by-day breakdown.