Skip to main content
A trace follows one request through your services as a tree of spans. Use this API to find traces, open one trace with its related errors and logs, and read the service map of a project.

​
List traces

Common query parameters:
  • from - optional ISO 8601 start timestamp
  • to - optional ISO 8601 end timestamp
  • environment - optional deployment environment filter
  • namespace - optional Kubernetes namespace filter from k8s.namespace.name
  • service_name - optional service filter
  • root_span - optional exact root span name
  • http_method - optional HTTP request method
  • http_status_code - optional three-digit HTTP response status code
  • min_duration - optional minimum duration in milliseconds
  • max_duration - optional maximum duration in milliseconds
  • status - optional ok or error
  • q - optional case-insensitive trace ID, root span, or service search
  • operation - optional normalized operation name (drilldown from the operations list)
  • limit
  • offset
Traces come newest first. The response carries data, limit, offset, total, and total_exact. To stay fast on long ranges, the list reads the newest hour, 6 hours, 24 hours, or 7 days first, and stops at the first of them that holds more matching traces than offset + limit. Then total_exact is false and total counts only the matching traces that start in that part of the range: the true count is at least total, and total is always larger than offset + limit, so another page exists. When the list reads the whole range, total_exact is true and total is the exact count. The dashboard filter sidebar loads values for environment, namespace, service, root span, HTTP method, and HTTP status code from the selected time range, each with its number of spans (root spans for a root span name). Each search box searches all values of its field, not only the listed ones. When the counts cannot cover the whole range, they and the matches come from the newest spans, and the sidebar shows the time they start from. Duration fields accept nanoseconds, microseconds, milliseconds, seconds, and minutes, then send millisecond values to the API.

​
List trace operations

Returns one row per (service_name, normalized operation) over the time window. Each row carries trace_count, error_count, error_rate, p50_ms, p95_ms, last_seen, and a 60-bucket sparkline. Use this when you want to see “what’s running and how often” instead of the raw trace stream. operation_name is normalized server-side: pure-digit path segments collapse to {n} and UUID segments collapse to {uuid}, so /users/12345/edit and /users/67890/edit group together as /users/{n}/edit. Drill down by passing the same operation value to the /v1/projects/{project_id}/traces endpoint. Common query parameters:
  • from - optional ISO 8601 start timestamp (defaults to 24h ago)
  • to - optional ISO 8601 end timestamp (defaults to now)
  • service_name - filter to a single service
  • environment - filter to a deployment environment
  • min_duration - optional minimum trace duration in milliseconds
  • status - optional ok or error
  • operation - optional normalized operation name (drilldown to a single operation)
  • sort - one of last_seen (default), count, p95, error_rate
  • limit - maximum rows to return (1..100, default 50)
The response sets high_cardinality_truncated: true when the project has more operations than limit. That usually means span names contain raw IDs or URLs; switching the SDK to emit http.route templates instead of full URLs fixes it.

​
Get request latency

Returns the p50, p95, and p99 duration of the requests in one time window. A request is an incoming span: a server span or a consumer span. Each percentile covers every request in the whole window. query monitors with source traces read the same numbers on every check. Query parameters:
  • from - optional ISO 8601 start of the window (defaults to 24 hours before to)
  • to - optional ISO 8601 end of the window, not included (defaults to now)
  • service_name - optional service filter
  • operation - optional span name or HTTP route, for example GET /cart/{id} or /cart/{id}
  • environment - optional deployment environment filter
The response carries span_count, p50_ms, p95_ms, and p99_ms, and the filters it used. When no request matches, span_count is 0 and the percentiles are null. The window can be at most 31 days.

​
Analyze database spans

The Traces dashboard includes a Database insights view for finding slow or failing database work before opening individual traces. It groups spans with db.system.name (or the older db.system) by database system, operation name, and calling service, then reports count, error count, error rate, p50/p95/p99 latency, last seen, and high-cardinality warnings. Use the Database insights view when database behavior matters more than raw trace volume. Filter by time range, environment, service, database system, operation name, or status, then select a row to open the matching trace list. Operation names prefer db.operation.name (or the older db.operation), then db.query.summary, and fall back to the span name.

​
Analyze HTTP routes

The Traces dashboard includes an HTTP view for finding slow or failing endpoints before opening individual traces. It groups server spans by http.route, http.request.method (or the older http.method), and service, then reports request count, error count, error rate, p50/p95/p99 latency, last seen, and high-cardinality warnings. Use the HTTP view when route-level behavior matters more than raw span names. Filter by time range, environment, service, method, route, status code, or status family, then select a row to open the matching trace list. For useful route groups, configure instrumentation to emit templated http.route values such as /api/users/{id}. Raw URLs still appear, but high-cardinality route values are flagged so they can be cleaned up at the instrumentation layer.

​
Analyze queues and messaging spans

The dashboard Queue insights view groups spans that include OpenTelemetry messaging semantic attributes. Use it to compare queue or topic throughput, latency, and error rate by destination, operation, service, and messaging system. To populate the view, send spans with messaging.system and a destination attribute such as messaging.destination.name, messaging.destination, or messaging.kafka.topic. Operation names use messaging.operation.type, messaging.operation.name, messaging.operation, or the span kind when no operation attribute is present. Click a queue insight row to drill into the matching trace list. The drilldown preserves the messaging system, destination, operation, service, time range, environment, and status filters so the trace samples match the aggregate row.

​
Get one trace

Returns the selected trace summary plus its spans. Each span includes its parent relationship, service, name, kind, status and status message, start and end times, duration, instrumentation scope, span attributes, resource attributes, events, links, trace state, and trace and span IDs. Span and resource attributes are flat objects with dotted keys, for example {"http.request.method": "GET", "http.response.status_code": "503"}. A span from an older SDK has the old and the current name, for example http.method and http.request.method; read the current name. Use the optional from and to ISO 8601 parameters when you know the time window. The time window limits the data scan and makes an exact trace lookup faster.

​
Inspect the trace waterfall

Open a trace in the dashboard to see its parent and child spans on a shared time axis. The waterfall uses a stable color for each service and marks error spans. The service name generates the color, so it stays consistent without project color settings. HTTP spans show method badges, and short durations use microsecond or nanosecond units when needed. You can:
  • Search spans by service, name, status, or attribute
  • Show only error spans
  • Collapse one branch, collapse all branches, or expand all branches
  • Zoom the time axis from 1x to 4x
  • Select a span to inspect its duration, position in the trace, status, IDs, attributes, and raw data
The span list and time axis scroll together. The span names stay visible while you move across a zoomed timeline, so you can compare a long request path without losing its service context.
Returns the error groups correlated to that trace.
Returns log events that carry the trace ID. Squasher bounds the lookup to the trace time window, with a small margin for delayed or adjacent log records. limit can be from 0 to 200.

​
Get the service map

This endpoint accepts the same time-window and filter parameters as trace listing except pagination. Use service_limit and call_limit to cap high-cardinality maps when rendering dashboard-style views. Common query parameters:
  • from - optional ISO 8601 start timestamp
  • to - optional ISO 8601 end timestamp
  • service_name - optional service filter
  • min_duration - optional minimum duration in milliseconds
  • status - optional ok or error
  • service_limit - optional maximum number of service nodes to return
  • call_limit - optional maximum number of service dependency edges to return
Example:

​
Agent handoff

Use traces when the user needs request-path evidence, service dependency context, or errors tied to one trace:
Use squasher traces operations, squasher traces list, squasher traces get, or MCP search("traces") followed by execute.