Usage

List usage logs

GET /api/usage

Returns paginated usage logs, newest first. Does not include request/response bodies — use the detail endpoint for those.

Query parameters

Parameter	Type	Description
model	string	Filter by model name (e.g. claude-haiku-4-5)
from	string	ISO date — only logs after this time
to	string	ISO date — only logs before this time
api_key_id	string	Filter by API key
proxy_endpoint_id	string	Filter by proxy endpoint
cursor	string	Pagination cursor from previous response
limit	number	Items per page (1–100, default 20)

Response

{
  "items": [
    {
      "id": "ae3c796c-18fe-49df-8ae0-25013a6c040c",
      "model": "claude-opus-4-6",
      "input_tokens": 12500,
      "output_tokens": 3200,
      "cache_creation_input_tokens": 8200,
      "cache_read_input_tokens": 0,
      "cost_cents": "5.55",
      "duration_ms": 4200,
      "status_code": 200,
      "proxy_endpoint_id": "...",
      "requested_at": "2026-03-17T01:19:55Z"
    }
  ],
  "nextCursor": "eyJ...",
  "hasMore": true
}

Example

# Get last 10 Opus calls
curl "https://codecosts.com/api/usage?model=claude-opus&limit=10" \
  -H "Authorization: Bearer $CODECOSTS_API_KEY"

---

Get usage detail

GET /api/usage/:id

Returns a single usage log with full request_body and response_body. Use this to inspect what was sent and received.

Response

Same fields as the list response, plus:

Field	Description
request_body	Full JSON request body (model, messages, tools, system prompt)
response_body	Full response — JSON for non-streaming, raw SSE text for streaming

Example

curl "https://codecosts.com/api/usage/ae3c796c-18fe-49df-8ae0-25013a6c040c" \
  -H "Authorization: Bearer $CODECOSTS_API_KEY"

---

Usage summary

GET /api/usage/summary

Returns aggregated usage statistics for the authenticated user’s organization. Aggregates all usage logs — no filter parameters.

Response

{
  "totalCostCents": 556.78,
  "totalRequests": 142,
  "totalInputTokens": 1250000,
  "totalOutputTokens": 320000,
  "byModel": [
    { "model": "claude-opus-4-6", "cost": 400.00, "requests": 20, "tokens": 500000 },
    { "model": "claude-sonnet-4-5", "cost": 150.00, "requests": 80, "tokens": 800000 },
    { "model": "claude-haiku-4-5", "cost": 6.78, "requests": 42, "tokens": 270000 }
  ],
  "byDay": [
    { "date": "2026-03-17", "cost": 45.50, "requests": 12 },
    { "date": "2026-03-16", "cost": 78.30, "requests": 25 }
  ]
}

Example

curl "https://codecosts.com/api/usage/summary" \
  -H "Authorization: Bearer $CODECOSTS_API_KEY"