cs log-ai: Log AI Token Usage and Costs to a Session

cs log-ai records AI provider, model, and token counts to the active session. Cost is auto-calculated for 42+ known models; provide -c for others.

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

cs log-ai [options]

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

When 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:

cs pricing list

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.