cs log-ai is how you manually tell CostHQ about an AI API call. You need this command whenever you are running a manual session or a custom agent workflow that is not already routing traffic through the CostHQ proxy. Each invocation creates one AI usage record attached to the active session (or to the session you specify with -s).
Usage
Flags
| Flag | Description |
|---|
-p, --provider <name> | AI provider (required). e.g. anthropic, openai, ollama |
-m, --model <name> | Model name (required) |
--prompt-tokens <n> | Input / prompt token count |
--completion-tokens <n> | Output / completion token count |
-t, --tokens <n> | Total tokens — use as an alternative to --prompt-tokens + --completion-tokens |
-c, --cost <amount> | Cost in USD. Auto-calculated from built-in pricing when the model is known; required otherwise |
--duration <duration> | Compute duration for local models (e.g. 120, 2m30s, 1h). Used to calculate cost instead of -c. |
--local | Force CostHQ to treat this as a local model and calculate cost from duration × hourly rate. |
-s, --session <id> | Target a specific session by ID instead of the active one |
--agent <name> | Agent name shown in the dashboard (useful when multiple agents share a session) |
--json | Machine-readable output |
Examples
# Auto-calculate cost from built-in pricing
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000
# Provide cost manually for an unknown model
cs log-ai -p openai -m gpt-4o -t 15000 -c 0.125
# Log local model usage with compute duration
cs log-ai -p ollama -m llama3 -t 5000 --duration 2m30s
# Target a specific session, label with agent name
cs log-ai -p anthropic -m claude-opus-4-6 --prompt-tokens 10000 --completion-tokens 5000 -s 42 --agent "Code Review Bot" --json
JSON Output
cs log-ai --json returns the logged usage entry plus a pricing object so you can verify how the cost was calculated:
{
"schemaVersion": 1,
"CostHQVersion": "3.1.1",
"id": 7,
"sessionId": 42,
"provider": "anthropic",
"model": "claude-sonnet-4",
"promptTokens": 8000,
"completionTokens": 2000,
"tokens": 10000,
"cost": 0.054,
"pricing": {
"source": "built-in",
"modelKnown": true,
"inputPer1M": 3.0,
"outputPer1M": 15.0
}
}
pricing.source values
| Value | Meaning |
|---|
"built-in" | Cost derived from CostHQ’s bundled pricing table |
"custom" | Cost derived from a price you set with cs pricing set |
"manual" | Cost taken directly from the -c flag you provided |
modelKnown is false, CostHQ cannot calculate cost automatically — you must supply -c <amount> or the entry will be recorded with cost: 0. Use cs pricing set to add a permanent custom price for that model so future calls calculate automatically.
Built-In Pricing Coverage
CostHQ ships with built-in pricing for 42+ models across Anthropic (Claude 3, Claude 3.5, Claude 4 families), OpenAI (GPT-4o, GPT-4, GPT-3.5, o1, o3 families), and OpenAI Codex. For the full list, run:
When you use cs run or the CostHQ proxy, cs log-ai is called automatically for every intercepted API call — you only need this command for manual sessions or custom agent workflows where you control the logging yourself.