Skip to main content
Read distributed tracing data with the Public API (V2): list performance and error traces, fetch the spans of a single trace, inspect aggregated actions and service dependencies, and analyze slow events. All endpoints authenticate with your personal API token. The trace endpoints use a site_ids array so they can search across multiple sites in one request. Most list and detail endpoints share the TracesQuery body and return either trace summaries or spans, described at the end of this page.

​
Locate a trace

Find the performance actions and error incidents a trace appears in, across sites. 
POST /api/v2/tracing/locator
The request body takes site_ids (a string array) and trace_id (a string). In return, you get a TraceLocation with performance entries (site_id, namespace, action_name) and errors entries (site_id, incident_number, exception_name).

​
Get the spans of a trace

Return every span in a trace. 
POST /api/v2/tracing/trace
The request body takes site_ids (a string array) and trace_id (a string), and returns an array of spans. 
{
  "site_ids": ["YOUR-SITE-ID"],
  "trace_id": "YOUR-TRACE-ID"
}
The POST /api/v2/tracing/trace/performance and POST /api/v2/tracing/trace/error endpoints return the spans of a performance or error trace using the TracesQuery body.

​
List traces

List performance or error traces. 
POST /api/v2/tracing/traces/performance
POST /api/v2/tracing/traces/errors
Both take the TracesQuery body and return an array of trace summaries. 
{
  "site_ids": ["YOUR-SITE-ID"],
  "action_name": "POST /api/users",
  "namespace": "web",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T23:59:59Z",
  "pagination": { "per_page": 50, "order": "DESC", "cursor": "Time" }
}
pagination takes per_page, order, and a cursor key. Set cursor to Time to paginate by trace time or Duration to paginate by total trace duration.

​
TracesQuery

FieldTypeRequiredDescription
site_idsstring[]YesSites to query.
paginationobjectYesPagination settings. Set cursor to Time or Duration.
digestsstring[]NoFilter by trace digests.
action_namestringNoFilter by action name.
namespacestringNoFilter by namespace.
querystringNoFree-text search query.
durationnumber (ms)NoMinimum duration filter.
fromstring (ISO 8601)NoTime range start.
tostring (ISO 8601)NoTime range end.
ttlnumberNoRetention boundary in seconds.

​
List performance actions

List performance actions with aggregated metrics. 
POST /api/v2/tracing/actions
The request body takes site_id, from, to, and the optional namespaces (array), revision, and action filters. You get back an array of action rows, each with namespace, action, digest, mean (ms), throughput, error_rate (0–100), and has_npo (whether an N+1 query was detected).

​
Service dependency edges

Map distributed tracing relationships between actions and services. 
POST /api/v2/tracing/action_edges
POST /api/v2/tracing/site_edges
action_edges returns the upstream (callers) and downstream (callees) edges for a focused action. Its body takes site_id, namespace (in "<service>/<namespace>" form, such as "PublicApi/web"), action, from, and to. site_edges returns upstream, downstream, and internal edges for a focused site. Its body takes site_id, from, and to. Each edge reports the peer service, request count, error_count, mean (ms), and p_90 / p_95 durations. Action edges also include the peer namespace, action, span kinds, and edge_type (SYNC or ASYNC).

​
Slow events

Analyze slow operations within traces, such as slow database queries. 
POST /api/v2/tracing/slow_events
POST /api/v2/tracing/slow_events/actions
slow_events returns aggregated slow events. Its body takes site_id, from, to, an optional span_kind, wanted_attributes, excluded_attributes, and a limit (defaults to 100). Each result has a digest, count, mean (ms), impact score, and attributes. slow_events/actions lists the actions a slow event appears in, by digest. Its body takes site_id, from, to, and digest. Each result has an action_name, namespace, count, trace_id, and start_time.

​
Trace summary fields

The list endpoints return trace summaries with these fields:
FieldTypeDescription
trace_idstringIdentifier for the whole trace.
span_idstringIdentifier for the root span.
site_idstringSite the trace belongs to.
namespacestringNamespace, such as web or background.
action_namestringAction name, such as POST /api/users.
revisionstringDeploy revision active when recorded.
timestring (ISO 8601)When the trace ended.
durationnumberTotal duration in milliseconds.
tagsobjectUser-defined tags from span attributes.
has_npobooleanWhether an N+1 query was detected.

​
Span fields

The trace detail endpoints return spans. Each span includes timing (start_time, end_time, duration in ms), identity (trace_id, span_id, parent_span_id, digest), and context (service_name, namespace, revision, action_name, span_name, span_kind, scope_name, scope_version). Status is reported with status_code (such as OK or ERROR) and status_message. Structured detail is returned as objects and arrays: resource_attributes and span_attributes (objects), events (with events.timestamp, events.name, and events.attributes arrays), and links (with links.trace_id, links.span_id, links.trace_state, and links.attributes arrays). subtrace_root indicates whether the span begins a separate service boundary.