API Reference
Traffic
Reading request records, metrics, charts, captured payloads and CSV exports.
The traffic endpoints read the organization's request records, the same data the Traffic page shows. They need the traffic:read scope and have no writes. See Traffic and Request Detail.
Endpoints
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/traffic/requests | List requests, newest first, with filters. Paginated, up to 200 per page. | traffic:read |
| GET | /v1/traffic/requests/{request_id} | Get one request record. | traffic:read |
| GET | /v1/traffic/requests/{request_id}/payload | Get a request's captured request and response bodies and headers. With reveal=true, also the originals of redacted values. | traffic:read; reveal also traffic:reveal |
| GET | /v1/traffic/metrics | List the metrics, stats and dimensions that stats and series accept. | traffic:read |
| GET | /v1/traffic/stats | Aggregate values for the metrics named, as comma-separated metric.stat ids. | traffic:read |
| GET | /v1/traffic/series | Chart series for the metrics named, as metric.stat or metric.stat@dimension ids, in buckets of bucket seconds, from 1 to 86400. | traffic:read |
| GET | /v1/traffic/export | Download the matching requests as CSV, newest first, up to 100,000 rows. | traffic:read |
The requests, stats, series and export endpoints take the same filters: start and end as RFC 3339 or epoch milliseconds, q, router_id, router_kind (static, fallback, weighted, claude_proxy, codex_proxy, gemini_proxy or adaptive_router), rule_id, feature_id, feature_prefix, model, provider, status (2xx, 4xx or 5xx), error_kind, streaming, session_id, correlation_id, comparison_id, role (primary or shadow), customer_user, and the machine identity issuer, subject and binding. An unknown parameter returns 400 unknown_parameter.
Two filters find what a detect_only or logs_only integration would have blocked. would_block=true matches requests where any integration recorded a would_block decision. would_block_by names an integration id, and repeats once per id; it matches requests where one of those integrations recorded would_block. Up to 32 ids of up to 128 characters each are accepted; more ids, or a longer or empty id, return 400 invalid_field. See Integrations.
Each record has the request's router, model, status, tokens, cost_micros, tool_calls, latency_ms, bytes, caller and prompt, and whether a payload is available. The single-request response holds the record in traffic_request. Payloads can contain prompts, headers and credentials sent with the request.
Total cost
cost.total is the summed cost of the matching requests, in micro-dollars (millionths of a US dollar), the same unit as each record's cost_micros. Divide by 1,000,000 for dollars. total in the response is the number of matching requests. Without start, the window is the 24 hours before end, which defaults to now. A window longer than 30 days, the retention period, returns 400 invalid_field for start.
Here the week cost $18.43 (18,432,750 micro-dollars) across 10,000 requests.
Revealing redacted values
A PII redaction integration with log_redaction reversible stores the payload with placeholders, and keeps the originals encrypted. GET .../payload?reveal=true returns the payload with redaction_map, a list of placeholder and original pairs. Ordinary payload reads never include it. Reveal needs traffic:read and traffic:reveal, which only an organization admin can grant and which traffic:read does not include; full control keys hold it. reveal accepts only true, with no other parameter. Every reveal attempt, including refused ones, is recorded in an audit log, and reveal responses carry Cache-Control: no-store.
A request without stored originals returns 404 payload_unavailable. A key without traffic:reveal returns 403 insufficient_scope, and too many reveals in a minute return 429 rate_limited.
Errors
| Code | Status | Meaning |
|---|---|---|
unknown_parameter | 400 | The query has a parameter the endpoint does not accept, or reveal is not true. |
invalid_field | 400 | A filter or metric has an invalid value, or stats and series have no metrics. |
insufficient_scope | 403 | A reveal from a key without traffic:reveal. |
not_found | 404 | No request has that id. |
payload_not_captured | 404 | No payload was captured for this request. |
payload_unavailable | 404 | The payload was captured but is no longer stored, or payload storage is off. |
payload_not_ready | 409 | The payload is still being written. Retry after retry_after_seconds. |
export_in_progress | 429 | Another export is running. |
rate_limited | 429 | Too many reveals in a minute. Retry later. |
payload_read_failed | 500 | The stored payload could not be read. Retry. |
traffic_unavailable | 503 | Traffic is unavailable. Retry. |