> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces API

> List traces, inspect a trace, fetch related errors, and query the project service map.

Use the Traces API to inspect distributed traces and the aggregated service map for a project.

## List traces

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/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

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/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

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/traces/{trace_id}
```

Returns the selected trace summary plus its spans.

## List errors related to a trace

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/traces/{trace_id}/errors
```

Returns the error groups correlated to that trace.

## Get the service map

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/services
```

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:

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/services?from=2026-04-01T00:00:00Z&to=2026-04-02T00:00:00Z&service_name=api&min_duration=250&status=error&service_limit=75&call_limit=150
```

## Agent handoff

Use traces when the user needs request-path evidence, service dependency context, or errors tied to one trace:

```text theme={null}
Inspect Squasher traces for project <project_id> from <from> to <to>. Start with trace operations for the service, narrow by operation or min_duration, fetch one trace, then fetch related errors if needed.
```

Use `squasher traces operations`, `squasher traces list`, `squasher traces get`, or MCP `search("traces")` followed by `execute`.