List traces failing a trace health check

List evaluated traces currently failing a specific check. Health checks use sampling, so this list is not exhaustive across ingested traces. List results in a time range of at most 31 days, by default the last 24 hours. Choose category trace_health (default) or conversation_view; use get_trace_health_summary with the same category to discover check IDs. While has_more is true, call again with next_cursor and the returned start_time and end_time.

GET/v1/projects/{projectId}/trace-health/checks/{checkId}/traces

Authorization

AuthorizationPersonal API key · headerrequired

Your personal API key from Settings > Personal API Keys, sent as Bearer <key>.

X-Organization-IdOrganization ID · headerrequired

The organization to act in. Copy it with Copy organization ID in the organization menu or the settings sidebar.

Path parameters

projectIdstringrequired

checkIdstringrequired

A check ID returned by the summary tool

Query parameters

categorystring

Choose instrumentation health or Conversation View compatibility checks

default: "trace_health"

Allowed:trace_healthconversation_view

start_timestring<date-time>

Inclusive ISO 8601 start timestamp with UTC offset; defaults to 24 hours before end_time

end_timestring<date-time>

Exclusive ISO 8601 end timestamp with UTC offset; defaults to now

limitinteger

min 1 · max 100 · default: 50

cursor_trace_started_atstring<date-time>

Trace start timestamp from next_cursor; must be supplied together with cursor_trace_id

cursor_trace_idstring

Trace ID from next_cursor; must be supplied together with cursor_trace_started_at

Responses

200

Response for status 200

start_timestringrequired

Resolved window start; pass it back with next_cursor

end_timestringrequired

Resolved window end; pass it back with next_cursor

tracesobject[]required

Show properties

Array of object

trace_idstringrequired

trace_started_atstringrequired

failed_countnumberrequired

example_span_idsstring[]required

examples_truncatedbooleanrequired

observed_through_ingested_atstringrequired

has_morebooleanrequired

next_cursorobject | nullrequired

Show properties

Any of:

object

trace_started_atstringrequired

trace_idstringrequired

null

null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Personal API keyOrganization IDRemember on this deviceInclude my values in samples

Parameters

projectIdpath*checkIdpath*A check ID returned by the summary toolcategoryqueryChoose instrumentation health or Conversation View compatibility checksstart_timequeryInclusive ISO 8601 start timestamp with UTC offset; defaults to 24 hours before end_timeend_timequeryExclusive ISO 8601 end timestamp with UTC offset; defaults to nowlimitquerycursor_trace_started_atqueryTrace start timestamp from next_cursor; must be supplied together with cursor_trace_idcursor_trace_idqueryTrace ID from next_cursor; must be supplied together with cursor_trace_started_at

Request

curl -X GET 'https://api.judgmentlabs.ai/v1/projects/YOUR_PROJECT_ID/trace-health/checks/YOUR_CHECK_ID/traces' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Organization-Id: YOUR_ORGANIZATION_ID' \
  -H 'Accept: application/json'

const response = await fetch("https://api.judgmentlabs.ai/v1/projects/YOUR_PROJECT_ID/trace-health/checks/YOUR_CHECK_ID/traces", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "X-Organization-Id": "YOUR_ORGANIZATION_ID",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.judgmentlabs.ai/v1/projects/YOUR_PROJECT_ID/trace-health/checks/YOUR_CHECK_ID/traces",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Organization-Id": "YOUR_ORGANIZATION_ID",
        "Accept": "application/json"
    },
)

Response

{
  "start_time": "string",
  "end_time": "string",
  "traces": [
    {
      "trace_id": "string",
      "trace_started_at": "string",
      "failed_count": 0,
      "example_span_ids": [
        "string"
      ],
      "examples_truncated": true,
      "observed_through_ingested_at": "string"
    }
  ],
  "has_more": true,
  "next_cursor": {
    "trace_started_at": "string",
    "trace_id": "string"
  }
}