ReferenceAPI reference
Usage
per-request lookups and the activity feed
GET
/v1/generation/{id}Authorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
id*string
Match
^[0-9A-HJKMNP-TV-Z]{26}$Response Body
application/json
application/json
curl -X GET "https://example.com/v1/generation/string"{ "id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE", "created": "2026-09-10T11:59:00.123Z", "model": "openai/gpt-5-mini", "resolved": { "provider": "openai", "endpoint_id": "ep_openai_gpt-5-mini_us", "upstream_model": "gpt-5-mini", "region": "us" }, "usage": { "input_tokens": 812, "output_tokens": 143, "cache_read_tokens": 0, "cache_write_tokens": 0, "reasoning_tokens": 0 }, "cost": { "total_micro_usd": 489, "lines": [ { "kind": "input", "units": 812, "unit_price_nano": 250, "micro_usd": 203 }, { "kind": "output", "units": 143, "unit_price_nano": 2000, "micro_usd": 286 } ], "price_version": "pv_01J9ZK2K4Q7Q3M3QX1V0F1PV01" }, "timing": { "ttft_ms": 190, "duration_ms": 1420, "gw_overhead_ms": 4 }, "stop": { "reason": "end_turn" }, "attempts": [ { "attempt": 1, "provider": "openai", "outcome": "ok", "http_status": 200, "ttft_ms": 186 } ], "warnings": []}GET
/v1/requestsAuthorization
bearer AuthorizationBearer <token>
In: header
Query Parameters
since?string
Format
date-timeuntil?string
Format
date-timeproject_id?string
key_id?string
model?string
provider?string
status?string
errors_only?boolean
fallbacks_only?boolean
min_cost_micro?integer
max_cost_micro?integer
q?string
request id prefix
limit?integer
Range
value <= 500Default
50cursor?string
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/requests"{ "object": "list", "data": [ { "request_id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE", "ts": "2026-09-10 11:59:00.123", "project_id": "prj_01J9ZK2K4Q7Q3M3QX1V0F1PRJ1", "key_id": "key_01J9ZK2K4Q7Q3M3QX1V0F1KEY1", "model": "openai/gpt-5-mini", "provider": "openai", "endpoint_id": "ep_openai_gpt-5-mini_us", "region": "us", "status": "ok", "http_status": 200, "error_code": "", "stop_reason": "end_turn", "attempts": 1, "input_tokens": 812, "cache_read_tokens": 0, "output_tokens": 143, "usage_source": "provider", "cost_micro": 489, "ttft_ms": 190, "duration_ms": 1420, "stream": true, "byok": false, "zdr": false, "logged": true, "app_id": "chatbot", "user_hash": "" } ], "next_cursor": "c2"}GET
/v1/requests/tailAuthorization
bearer AuthorizationBearer <token>
In: header
Query Parameters
after?string
resume after this request id
interval_ms?integer
Range
500 <= value <= 30000Default
2000Response Body
text/event-stream
application/json
curl -X GET "https://example.com/v1/requests/tail""string"GET
/v1/requests/{id}Authorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
id*string
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/requests/string"{ "request_id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE", "ts": "2026-09-10 11:59:00.123", "project_id": "prj_01J9ZK2K4Q7Q3M3QX1V0F1PRJ1", "key_id": "key_01J9ZK2K4Q7Q3M3QX1V0F1KEY1", "model": "openai/gpt-5-mini", "provider": "openai", "endpoint_id": "ep_openai_gpt-5-mini_us", "region": "us", "status": "ok", "http_status": 200, "error_code": "", "stop_reason": "end_turn", "attempts": 1, "input_tokens": 812, "cache_read_tokens": 0, "output_tokens": 143, "usage_source": "provider", "cost_micro": 489, "ttft_ms": 190, "duration_ms": 1420, "stream": true, "byok": false, "zdr": false, "logged": true, "app_id": "chatbot", "user_hash": "", "cell": "in1", "dialect_in": "openai", "upstream_model": "gpt-5-mini", "price_version_id": "pv_01J9ZK2K4Q7Q3M3QX1V0F1PV01", "upstream_ttft_ms": 186, "gw_overhead_ms": 4, "bytes_in": 2048, "bytes_out": 1536, "tool_calls": 0, "has_images": false, "has_tools": false, "has_schema": false, "cache_write_tokens": 0, "reasoning_tokens": 0, "tags": { "env": "prod" }, "user_agent": "openai-python/1.60", "client_ip_prefix": "203.0.113.0/24", "route_trace": "", "timing": { "ttft_ms": 190, "upstream_ttft_ms": 186, "duration_ms": 1420, "gw_overhead_ms": 4 }, "usage": { "source": "provider", "normalised": { "input_tokens": 812, "output_tokens": 143, "cache_read_tokens": 0, "cache_write_tokens": 0, "reasoning_tokens": 0 } }, "attempt_rows": [ { "attempt": 1, "ts": "2026-09-10 11:59:00.130", "provider": "openai", "endpoint_id": "ep_openai_gpt-5-mini_us", "pool_id": "pool_openai", "key_hint": "sk-…9x", "outcome": "ok", "http_status": 200, "error_class": "", "ttft_ms": 186, "duration_ms": 1410, "output_tokens": 143 } ], "payload_state": "available", "request": { "model": "openai/gpt-5-mini", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "hi" } ] } ] }, "response": { "candidates": [ { "index": 0, "content": [ { "type": "text", "text": "Hello! How can I help?" } ], "stop": { "reason": "end_turn" } } ], "usage": { "input_tokens": 812, "output_tokens": 143, "cache_read_tokens": 0, "cache_write_tokens": 0, "reasoning_tokens": 0 }, "cost": { "total_micro_usd": 489, "lines": [ { "kind": "input", "units": 812, "unit_price_nano": 250, "micro_usd": 203 }, { "kind": "output", "units": 143, "unit_price_nano": 2000, "micro_usd": 286 } ], "price_version": "pv_01J9ZK2K4Q7Q3M3QX1V0F1PV01" } }}GET
/v1/usageAuthorization
bearer AuthorizationBearer <token>
In: header
Query Parameters
range?unknown
Default
"24h"Value in
- "24h"
- "7d"
- "30d"
- "90d"
- "custom"
from?string
Format
date-timeto?string
Format
date-timegranularity?unknown
ranges over 30 d default to day; over 90 d force day
Value in
- "hour"
- "day"
group_by?unknown
Value in
- "project"
- "key"
- "model"
- "provider"
- "byok"
- "app"
- "tag"
tag?string
tag key for group_by=tag
compare?boolean
project_id?string
key_id?string
model?string
provider?string
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/usage"{ "object": "usage", "range": { "from": "2026-09-09T12:00:00Z", "to": "2026-09-10T12:00:00Z", "granularity": "hour" }, "group_by": "model", "totals": { "requests": 12000, "ok": 11930, "errors": 70, "input_tokens": 9600000, "output_tokens": 1700000, "cache_read_tokens": 400000, "cache_write_tokens": 0, "reasoning_tokens": 0, "cost_micro": 5800000 }, "series": [ { "requests": 12000, "ok": 11930, "errors": 70, "input_tokens": 9600000, "output_tokens": 1700000, "cache_read_tokens": 400000, "cache_write_tokens": 0, "reasoning_tokens": 0, "cost_micro": 5800000, "bucket": "2026-09-10T11:00:00Z" } ], "groups": [ { "requests": 12000, "ok": 11930, "errors": 70, "input_tokens": 9600000, "output_tokens": 1700000, "cache_read_tokens": 400000, "cache_write_tokens": 0, "reasoning_tokens": 0, "cost_micro": 5800000, "key": "openai/gpt-5-mini" } ]}