Skip to main content

​
Usage Tools

Most tools accept optional format (markdown or json). Write tools that upload data (costhawk_sync_*) also accept optional apiKey to override COSTHAWK_API_KEY.
MCP is fully supported. Local sync tools (costhawk_sync_*, costhawk_list_*_sessions, costhawk_get_local_*) remain available and are not being removed in the current release line.

​
costhawk_get_usage_summary

Get a summary of your AI API usage and costs over a time period. Parameters:
ParameterTypeRequiredDescription
periodstringNoPreset: last_24h, today, yesterday, last_7d, last_30d
startDatestringNoStart date (ISO 8601)
endDatestringNoEnd date (ISO 8601)
formatstringNomarkdown (default) or json
Example:
“Show me my API usage for the last 7 days”

​
costhawk_get_usage_by_tag

Break down costs by metadata tags like project, environment, or team. Parameters:
ParameterTypeRequiredDescription
tagKeystringYesTag to group by (e.g., project, environment)
startDatestringNoStart date (ISO 8601)
endDatestringNoEnd date (ISO 8601)
limitnumberNoMax results (1-100, default 20)
Example:
“Show me costs broken down by project tag”

​
Savings Tools

​
costhawk_get_savings

Show savings vs retail pricing for flat-rate subscriptions like Claude Max or OpenAI Pro. Parameters:
ParameterTypeRequiredDescription
periodstringNodaily, weekly, or monthly
datestringNoAnchor date (ISO 8601)
Example:
“Am I saving money with Claude Max this month?“

​
costhawk_list_subscriptions

List your active flat-rate subscriptions. Example:
“What subscriptions do I have configured?“

​
costhawk_get_savings_breakdown

Get per-model usage and retail cost breakdown. Parameters:
ParameterTypeRequiredDescription
periodstringNodaily, weekly, or monthly
datestringNoAnchor date (ISO 8601)
Example:
“Break down my savings by model”

​
Monitoring Tools

​
costhawk_detect_anomalies

Find cost spikes and unusual activity patterns. Example:
“Are there any cost anomalies I should know about?“

​
costhawk_list_alerts

View recent alerts including budget warnings, cost spikes, and anomaly notifications. Parameters:
ParameterTypeRequiredDescription
limitnumberNoMax alerts (1-100, default 20)
unreadOnlybooleanNoShow only unread alerts
Example:
“Show me my unread alerts”

​
Webhook Tools

​
costhawk_list_webhooks

List all configured webhooks for receiving cost alerts. Example:
“What webhooks do I have set up?“

​
costhawk_create_webhook

Create a new webhook to receive notifications. Parameters:
ParameterTypeRequiredDescription
namestringYesWebhook name
urlstringYesWebhook URL
typestringYesslack, discord, teams, pagerduty, or custom
eventsarrayYesEvents: cost_spike, budget_alert, anomaly, etc.
Example:
“Create a Slack webhook for budget alerts at https://hooks.slack.com/…”

​
Pricing Tools

​
costhawk_get_model_pricing

Look up current pricing for AI models. Parameters:
ParameterTypeRequiredDescription
providerstringNoFilter by provider: openai, anthropic, google, etc.
Example:
“What’s the current pricing for Claude Opus?”

​
Local Sync Tools

​
costhawk_sync_claude_code_usage

Sync Claude Code usage from local transcript files and upload usage metadata to CostHawk. Parameters:
ParameterTypeRequiredDescription
maxAgeHoursnumberNoOnly include sessions modified in the last N hours (default 720)
dryRunbooleanNoPreview payload without uploading
previewLimitnumberNoNumber of sessions in dry-run preview (default 3)
includeFileListbooleanNoInclude local file paths read by parser
formatstringNomarkdown (default) or json
Example:
“Sync my Claude Code usage”
With dry run:
“Preview my Claude Code sync payload”

​
costhawk_list_claude_code_sessions

List Claude Code sessions discovered locally before syncing. Parameters:
ParameterTypeRequiredDescription
maxAgeHoursnumberNoOnly include sessions modified in the last N hours (default 168)
limitnumberNoMaximum sessions to return (default 20)
formatstringNomarkdown (default) or json

​
costhawk_get_local_claude_code_usage

Compute Claude Code usage locally without uploading anything. Parameters:
ParameterTypeRequiredDescription
maxAgeHoursnumberNoOnly include sessions modified in the last N hours (default 24)
subscriptionPlanstringNopro, max_5x, or max_20x (adds local savings estimate)
formatstringNomarkdown (default) or json

​
costhawk_sync_codex_usage

Sync OpenAI Codex CLI usage from local session logs and upload usage metadata to CostHawk. Parameters:
ParameterTypeRequiredDescription
maxAgeHoursnumberNoOnly include sessions modified in the last N hours (default 720)
dryRunbooleanNoPreview payload without uploading
previewLimitnumberNoNumber of sessions in dry-run preview (default 3)
includeFileListbooleanNoInclude local file paths read by parser
formatstringNomarkdown (default) or json
Example:
“Sync my Codex usage”
Codex sync can be disabled globally with COSTHAWK_CODEX_AUTO_SYNC=false.

​
costhawk_list_codex_sessions

List Codex sessions discovered locally before syncing. Parameters:
ParameterTypeRequiredDescription
maxAgeHoursnumberNoOnly include sessions modified in the last N hours (default 168)
limitnumberNoMaximum sessions to return (default 20)
formatstringNomarkdown (default) or json

​
costhawk_get_local_codex_usage

Compute Codex usage locally without uploading anything. Parameters:
ParameterTypeRequiredDescription
maxAgeHoursnumberNoOnly include sessions modified in the last N hours (default 24)
formatstringNomarkdown (default) or json
If Codex files are in a non-standard directory, set COSTHAWK_CODEX_SESSIONS_DIR in MCP env and restart your MCP host.

​
Privacy Tools

​
What We Send

When syncing local data, CostHawk only uploads usage metadata: 
{
  "sessions": [
    {
      "sessionId": "hashed_abc123",
      "projectId": "hashed_project_id",
      "model": "claude-3-5-sonnet-20241022",
      "inputTokens": 15420,
      "outputTokens": 8230,
      "cacheReadTokens": 5000,
      "cacheCreationTokens": 1200,
      "timestamp": "2025-02-03T10:30:00Z"
    }
  ]
}
No code, prompts, file paths, or project names are ever sent.