Traces

Search, inspect, tag, and re-evaluate traces in a project.

Commands

Command	Description
`traces add-tags`	Add tags to a trace.
`traces behaviors`	List behaviors observed on a trace.
`traces evaluate`	Re-evaluate traces.
`traces get`	Get a trace by ID.
`traces search`	Search traces.
`traces span`	Get span details.
`traces spans`	List a trace’s spans.
`traces tags`	List a trace’s tags.

`traces add-tags`

Add tags to a trace.

Attach one or more string tags to an existing trace. Tags are additive — existing tags are preserved.

judgment traces add-tags [OPTIONS] <PROJECT_ID> <TRACE_ID>

Arguments

Name	Required
`PROJECT_ID`	yes
`TRACE_ID`	yes

Options

Flag	Type	Required	Description
`--tags`	text	yes	String tags to attach to the trace. Tags are additive — existing tags on the trace are preserved.

`traces behaviors`

List behaviors observed on a trace.

judgment traces behaviors <PROJECT_ID> <TRACE_ID>

Arguments

Name	Required
`PROJECT_ID`	yes
`TRACE_ID`	yes

`traces evaluate`

Re-evaluate traces.

Queue traces for re-evaluation by the project’s judges. Pass trace_ids to re-evaluate specific traces, or evaluate_all: true to re-evaluate every trace in the project.

judgment traces evaluate [OPTIONS] <PROJECT_ID>

Arguments

Name	Required
`PROJECT_ID`	yes

Options

Flag	Type	Required	Description
`--evaluate-all`	boolean	no	When true, re-evaluate every trace in the project. Mutually exclusive with `trace_ids`.
`--trace-ids`	text	no	Trace UUIDs to re-evaluate. Mutually exclusive with `evaluate_all`.
`--specific-judge-names`	text	no	Restrict evaluation to judges with these names. Omit to run every applicable judge.

`traces get`

Get a trace by ID.

judgment traces get <PROJECT_ID> <TRACE_ID>

Arguments

Name	Required
`PROJECT_ID`	yes
`TRACE_ID`	yes

`traces search`

Search traces.

Filter, sort, time-bound, and paginate traces in a project. See each body field for the exact JSON shape it expects.

judgment traces search [OPTIONS] <PROJECT_ID>

Arguments

Name	Required
`PROJECT_ID`	yes

Options

Flag	Type	Required	Description
`--filters`	text	no	Filter expressions, ANDed together. Each item is `{"field":<field>,"op":<op>,"value":<value>}`. Allowed ops depend on the field's type. Op groups: - `STRING_OPS` = `=` \| `!=` \| `contains` \| `does_not_contain` \| `exists` \| `is_absent` - `NUMERIC_OPS` = `=` \| `!=` \| `<` \| `<=` \| `>` \| `>=` - `ARRAY_ANY` = `any` (matches when the row's array overlaps the supplied values) String fields (op in STRING_OPS, value is a string): `span_name`, `customer_id`, `customer_user_id`, `session_id`, `error`, `dataset_id`. Numeric fields (op in NUMERIC_OPS, value is a number): `duration` (nanoseconds), `llm_cost` (USD). Array fields (op = `any`, value is an array): `tags` (strings), `rules_invoked` (rule names from this project, strings), `behaviors` (behavior UUIDs). Special: - `full_text_search`: op = `contains`, value is a string searched across span attribute text. - `span_attributes_roots`: matches a single span attribute key/value: `{"field":"span_attributes_roots","key":"<attribute-name>","op":<STRING_OPS>,"value":"<string>"}`
`--sort-by`	text	no	`{"field":<sort_field>,"direction":"asc"\|"desc"}` where `sort_field` is one of: `created_at`, `span_name`, `duration`, `llm_cost`. Default when omitted: `{"field":"created_at","direction":"desc"}`.
`--time-range`	text	no	`{"start_time":<iso8601-string>\|null,"end_time":<iso8601-string>\|null}`. Either bound may be null to leave that side open. Invalid timestamps return 400.
`--pagination`	text	yes	`{"limit":<int 1-200>,"cursorSortValue":<string>\|null,"cursorItemId":<string>\|null}`. First page: pass null for both cursor fields. Each response returns `nextCursor:{sort_value,trace_id}` (or null when `hasMore=false`); copy those into `cursorSortValue` and `cursorItemId` for the next page.

`traces span`

Get span details.

Fetch full details (inputs/outputs/attributes) for up to 20 specific spans across one or more traces.

judgment traces span [OPTIONS] <PROJECT_ID>

Arguments

Name	Required
`PROJECT_ID`	yes

Options

Flag	Type	Required	Description
`--spans`	text	yes	Up to 20 trace/span ID pairs to fetch span details for in a single request.

`traces spans`

List a trace’s spans.

judgment traces spans <PROJECT_ID> <TRACE_ID>

Arguments

Name	Required
`PROJECT_ID`	yes
`TRACE_ID`	yes

`traces tags`

List a trace’s tags.

judgment traces tags <PROJECT_ID> <TRACE_ID>

Arguments

Name	Required
`PROJECT_ID`	yes
`TRACE_ID`	yes

Traces

On this page