Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Search captured requests by model, time, status, or metadata
GET /v1/traces?limit=50&model_id=gpt-4o HTTP/1.1
Host: localhost:8000
| Param | Type | Default | Notes |
|---|---|---|---|
limit | int | 100 | Max rows to return. Hard cap: 1000. |
offset | int | 0 | For pagination. |
start_date | ISO 8601 | — | Inclusive lower bound on created_at. |
end_date | ISO 8601 | — | Exclusive upper bound on created_at. |
source | string | — | Filter by source / tenant / integration tag. |
model_id | string | — | Filter by concrete model (e.g. gpt-4o-mini). |
status | string | — | success, error, or timeout. |
{
"traces": [
{
"request_id": "t_af91",
"model": "gpt-4o-mini",
"provider": "openai",
"tokens_in": 214,
"tokens_out": 88,
"cost_usd": 0.00046,
"latency_ms": 612.3,
"status": "success",
"created_at": "2026-04-19T12:04:07Z"
}
],
"total": 5423,
"has_more": true
}
total is the full match count ignoring limit/offset, so you can
render pagination UI without a second query.
# Last 50 gpt-4o-mini calls
curl -s "http://localhost:8000/v1/traces?limit=50&model_id=gpt-4o-mini" | jq .
# Errors in the last 24h
curl -s "http://localhost:8000/v1/traces?status=error&start_date=2026-04-18T00:00:00Z" | jq .
# Cost by day for the last week — lean on jq
curl -s "http://localhost:8000/v1/traces?limit=1000&start_date=2026-04-12T00:00:00Z" \
| jq '[.traces[] | {day: .created_at[0:10], cost: .cost_usd}] | group_by(.day) | map({day: .[0].day, total: (map(.cost) | add)})'
curl -s "http://localhost:8000/v1/traces/t_af91" | jq .
{
"request_id": "t_af91",
"input_text": "...the full user message...",
"output_text": "...the full assistant response...",
"metadata": { "user_id": "u_42", "feature": "ticket_classifier" },
/* plus all summary fields */
}
OPENTRACY_TRACE_CONTENT=false, the
input_text and output_text fields are omitted — the row keeps its
cost/latency/metadata, but the content was never persisted. See
Traces → Privacy.| Status | error.code | Meaning |
|---|---|---|
400 | invalid_request | Bad date format or limit out of range. |
404 | trace_not_found | Specific request_id not in ClickHouse. |
503 | clickhouse_down | OPENTRACY_CH_ENABLED=false or connection failed. |