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

# Querying traces

Read distributed tracing data with the [Public API (V2)](/api/v2/overview): 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](#trace-summary-fields) or [spans](#span-fields), described at
the end of this page.

## Locate a trace

Find the performance actions and error incidents a trace appears in, across
sites.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/tracing/locator
  ```
</CodeGroup>

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.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/tracing/trace
  ```
</CodeGroup>

The request body takes `site_ids` (a string array) and `trace_id` (a string),
and returns an array of [spans](#span-fields).

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_ids": ["YOUR-SITE-ID"],
    "trace_id": "YOUR-TRACE-ID"
  }
  ```
</CodeGroup>

The `POST /api/v2/tracing/trace/performance` and `POST /api/v2/tracing/trace/error`
endpoints return the [spans](#span-fields) of a performance or error trace using
the [`TracesQuery`](#tracesquery) body.

## List traces

List performance or error traces.

<CodeGroup>
  ```shell Endpoints theme={null}
  POST /api/v2/tracing/traces/performance
  POST /api/v2/tracing/traces/errors
  ```
</CodeGroup>

Both take the [`TracesQuery`](#tracesquery) body and return an array of [trace
summaries](#trace-summary-fields).

<CodeGroup>
  ```json body.json theme={null}
  {
    "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" }
  }
  ```
</CodeGroup>

`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

| Field         | Type              | Required | Description                                                |
| ------------- | ----------------- | -------- | ---------------------------------------------------------- |
| `site_ids`    | string\[]         | Yes      | Sites to query.                                            |
| `pagination`  | object            | Yes      | Pagination settings. Set `cursor` to `Time` or `Duration`. |
| `digests`     | string\[]         | No       | Filter by trace digests.                                   |
| `action_name` | string            | No       | Filter by action name.                                     |
| `namespace`   | string            | No       | Filter by namespace.                                       |
| `query`       | string            | No       | Free-text search query.                                    |
| `duration`    | number (ms)       | No       | Minimum duration filter.                                   |
| `from`        | string (ISO 8601) | No       | Time range start.                                          |
| `to`          | string (ISO 8601) | No       | Time range end.                                            |
| `ttl`         | number            | No       | Retention boundary in seconds.                             |

## List performance actions

List performance actions with aggregated metrics.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/tracing/actions
  ```
</CodeGroup>

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.

<CodeGroup>
  ```shell Endpoints theme={null}
  POST /api/v2/tracing/action_edges
  POST /api/v2/tracing/site_edges
  ```
</CodeGroup>

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

<CodeGroup>
  ```shell Endpoints theme={null}
  POST /api/v2/tracing/slow_events
  POST /api/v2/tracing/slow_events/actions
  ```
</CodeGroup>

`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:

| Field         | Type              | Description                               |
| ------------- | ----------------- | ----------------------------------------- |
| `trace_id`    | string            | Identifier for the whole trace.           |
| `span_id`     | string            | Identifier for the root span.             |
| `site_id`     | string            | Site the trace belongs to.                |
| `namespace`   | string            | Namespace, such as `web` or `background`. |
| `action_name` | string            | Action name, such as `POST /api/users`.   |
| `revision`    | string            | Deploy revision active when recorded.     |
| `time`        | string (ISO 8601) | When the trace ended.                     |
| `duration`    | number            | Total duration in milliseconds.           |
| `tags`        | object            | User-defined tags from span attributes.   |
| `has_npo`     | boolean           | Whether 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.