Skip to main content
The management API’s trace search endpoint. Returns rows from ClickHouse matching the filters you pass as query parameters. 
GET /v1/traces?limit=50&model_id=gpt-4o HTTP/1.1
Host: localhost:8000

​
Query parameters

ParamTypeDefaultNotes
limitint100Max rows to return. Hard cap: 1000.
offsetint0For pagination.
start_dateISO 8601—Inclusive lower bound on created_at.
end_dateISO 8601—Exclusive upper bound on created_at.
sourcestring—Filter by source / tenant / integration tag.
model_idstring—Filter by concrete model (e.g. gpt-4o-mini).
statusstring—success, error, or timeout.

​
Response

{
  "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.

​
Curl

# 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)})'

​
Full trace content

The list endpoint returns a summary row. To fetch the full prompt and response text for one trace, hit: 
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 */
}
If the engine is running with 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.

​
Errors

Statuserror.codeMeaning
400invalid_requestBad date format or limit out of range.
404trace_not_foundSpecific request_id not in ClickHouse.
503clickhouse_downOPENTRACY_CH_ENABLED=false or connection failed.