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
  • service_name - optional service filter
  • min_duration - optional minimum duration in milliseconds
  • status - optional ok or error
  • operation - optional normalized operation name (drilldown from the operations list)
  • limit
  • offset

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

​
Get one trace

Returns the selected trace summary plus its spans.
Returns the error groups correlated to that trace.

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