Get Request Logs

Retrieve request-level logs with billing breakdown fields.

GET/v1/customer/logs

Request Parameters

Name	Type	Description
limit	integer	Maximum number of rows to return. Defaults to 50, capped at 100.
offset	integer	Pagination offset.
status	"success" \| "error"	Filter by final request status.
model	string	Filter by requested model alias.
start_date	string (YYYY-MM-DD or ISO-8601)	Inclusive start of the requested window.
end_date	string (YYYY-MM-DD or ISO-8601)	Inclusive end of the requested window.
api_key_id	string	Filter to a single API key owned by the tenant.

Response Fields

Name	Type	Description
logs[].traffic_mode	"shared" \| "byok"	How the winning route was billed.
logs[].cost_breakdown.model_charge	integer (credits)	Shared-capacity model charge. This is 0 on BYOK requests.
logs[].cost_breakdown.byok_platform_fee	integer (credits)	Platform fee charged on BYOK requests.
logs[].cost_breakdown.managed_tool_fee	integer (credits)	Managed tool fee charged on the request, such as TheRouter Web Search.
logs[].cost_breakdown.agent_runtime_fee	integer (credits)	Agent/runtime fee. Present for forward compatibility and 0 until runtime monetization is live.
logs[].cost_breakdown.total_charge	integer (credits)	Total charge applied to the request ledger.
logs[].skills_used	string[]	Built-in or customer-managed skills used on the request when available.
logs[].billing_note	string \| null	Human-readable BYOK note clarifying that upstream model usage is billed by your provider.

Request Example

bash

curl "https://api.therouter.ai/v1/customer/logs?limit=20&start_date=2026-02-01&end_date=2026-02-07" \
  -H "Authorization: Bearer $THEROUTER_API_KEY"

Response Example

json

{
  "logs": [
    {
      "id": "req_row_123",
      "request_id": "req_abc123",
      "model": "openai/gpt-4o",
      "provider": "openai",
      "status": "success",
      "traffic_mode": "byok",
      "tokens": {
        "prompt": 812,
        "completion": 124,
        "total": 936
      },
      "cost": 3,
      "cost_breakdown": {
        "model_charge": 0,
        "byok_platform_fee": 3,
        "managed_tool_fee": 0,
        "agent_runtime_fee": 0,
        "total_charge": 3
      },
      "skills_used": [],
      "billing_note": "Upstream model usage is billed by your provider. TheRouter only charged the BYOK platform fee and any managed tool or runtime fees.",
      "latency_ms": 412,
      "created_at": "2026-02-07T10:14:22.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

CSV Export

bash

curl "https://api.therouter.ai/v1/customer/logs/export.csv?start_date=2026-02-01&end_date=2026-02-07" \
  -H "Authorization: Bearer $THEROUTER_API_KEY"

When to use this endpoint

Use request logs for request-level billing forensics and chargeback workflows. Use analytics for grouped reporting. Use the monthly usage statement for a finance-friendly ledger export scoped to one calendar month.