Skip to main content

​
Get Usage Summary

Retrieve a summary of API usage and costs for a time period. 
GET /api/mcp/usage/summary

​
Query Parameters

ParameterTypeRequiredDescription
startDatestringNoStart date (ISO 8601). Default: 30 days ago
endDatestringNoEnd date (ISO 8601). Default: now

​
Response

{
  "totalCost": 45.23,
  "totalCalls": 1250,
  "totalInputTokens": 2500000,
  "totalOutputTokens": 750000,
  "byProvider": {
    "anthropic": { "cost": 30.15, "calls": 800 },
    "openai": { "cost": 15.08, "calls": 450 }
  },
  "byModel": {
    "claude-3-5-sonnet": { "cost": 25.00, "calls": 600 },
    "gpt-4o": { "cost": 15.08, "calls": 450 }
  },
  "period": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-19T23:59:59Z"
  }
}

​
Example

curl -X GET "https://costhawk.ai/api/mcp/usage/summary?startDate=2026-01-01" \
  -H "Authorization: Bearer ch_sk_your_token"

​
Get Usage by Tag

Break down usage and costs by a metadata tag. 
GET /api/mcp/usage/by-tag

​
Query Parameters

ParameterTypeRequiredDescription
tagKeystringYesTag key to group by (e.g., project, environment)
startDatestringNoStart date (ISO 8601)
endDatestringNoEnd date (ISO 8601)
limitnumberNoMax results (1-100). Default: 20

​
Response

[
  {
    "tag": "project",
    "value": "chatbot",
    "cost": 25.50,
    "calls": 600,
    "percentage": 56.4
  },
  {
    "tag": "project",
    "value": "search",
    "cost": 19.73,
    "calls": 650,
    "percentage": 43.6
  }
]

​
Example

curl -X GET "https://costhawk.ai/api/mcp/usage/by-tag?tagKey=project" \
  -H "Authorization: Bearer ch_sk_your_token"