Traces & Usage

Get trace detail

GET /api/usage/:id

Returns a single trace with the full request and response bodies — exactly what was sent to Anthropic and what came back. This is the only endpoint that returns bodies.

Tip

The list endpoint (GET /api/usage) returns metadata only — no bodies. Always use this detail endpoint when you need to inspect a specific API call.

Response

Field	Type	Description
id	string	Trace ID
model	string	Model that handled the request
input_tokens	number	Input tokens consumed
output_tokens	number	Output tokens generated
cache_creation_input_tokens	number	Tokens for prompt cache creation
cache_read_input_tokens	number	Tokens read from prompt cache
cost_cents	string	Calculated cost in cents
duration_ms	number	Round-trip time to Anthropic
status_code	number	HTTP status from Anthropic
proxy_endpoint_id	string	Proxy endpoint that handled this request
requested_at	string	ISO timestamp
request_body	string | null	Full JSON request sent to Anthropic (model, messages, tools, system prompt, thinking config)
response_body	string | null	Full response — JSON for non-streaming, raw SSE text for streaming

Both body fields are stored as text. Parse request_body as JSON. For response_body, check whether it starts with event: to determine if it’s SSE (streaming) or JSON (non-streaming).

{
  "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",
  "request_body": "{\"model\":\"claude-opus-4-6\",\"max_tokens\":4096,\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}",
  "response_body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{...}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"delta\":{\"type\":\"text_delta\",\"text\":\"Hi!\"}}\n\n..."
}

Example

# Get full trace with request/response bodies
curl "https://codecosts.com/api/usage/ae3c796c-18fe-49df-8ae0-25013a6c040c" \
  -H "Authorization: Bearer $CODECOSTS_API_KEY"

---

List usage logs

GET /api/usage

Returns paginated usage logs, newest first. Use this to browse or filter traces.

Note

This endpoint returns metadata only — no request/response bodies. To get bodies, fetch a specific trace with GET /api/usage/:id.

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"

---

Usage summary

GET /api/usage/summary

Returns aggregated usage statistics for the authenticated user’s organization.

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"