Skip to main content
GET
List traces with cursor-based pagination

Authorizations

Authorization
string
header
required

SDK API key (tl_...) or Clerk session JWT

Query Parameters

project_id
string<uuid>
model
string
error
boolean
failure_type
enum<string>

Filter traces with spans matching this failure type (e.g. timeout, rate_limit, invalid_response, context_length)

Available options:
timeout,
rate_limit,
invalid_response,
context_length
from
string<date-time>
to
string<date-time>
latency_min
integer

Minimum trace latency in milliseconds (inclusive). Must be a non-negative integer.

Required range: x >= 0
latency_max
integer

Maximum trace latency in milliseconds (inclusive). Must be a non-negative integer and greater than or equal to latency_min when both are supplied.

Required range: x >= 0
token_count_min
integer

Minimum total token count (prompt + completion, summed across spans) for the trace (inclusive). Must be a non-negative integer. Traces ingested before TRU-250 report total_token_count = 0 and are therefore excluded by any non-zero minimum.

Required range: x >= 0
token_count_max
integer

Maximum total token count for the trace (inclusive). Must be a non-negative integer and greater than or equal to token_count_min when both are supplied.

Required range: x >= 0
tag_key
string

Filter traces whose tags column contains the tag_keytag_value pair (TRU-215). Must be supplied together with tag_value; providing only one side returns 400 error.tags_filter_incomplete.

tag_value
string

Filter value paired with tag_key. See tag_key for constraints.

cursor
string
limit
integer
default:50
Required range: 1 <= x <= 200

Response

Trace list

traces
object[]
required
has_more
boolean
required
next_cursor
string | null