Skip to main content
Use the Traces API to inspect distributed traces and the aggregated service map for 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
The dashboard filter sidebar loads values for environment, namespace, service, root span, HTTP method, and HTTP status code from the selected time range. 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.

​
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 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, then db.operation, then db.query.summary, and fall back to the span name when only db.system is available.

​
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, 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.

​
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.