> ## 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.
# Traces opvragen
Lees distributed tracing-gegevens met de [Public API (V2)](/api/v2/overview): som
performance- en error-traces op, haal de spans van een enkele trace op, inspecteer
geaggregeerde acties en service-afhankelijkheden, en analyseer trage events. Alle
eindpunten authenticeren met uw persoonlijke API-token. De trace-eindpunten gebruiken een
`site_ids`-array zodat ze in één verzoek over meerdere sites kunnen zoeken.
De meeste lijst- en detail-eindpunten delen de `TracesQuery`-body en retourneren ofwel
[trace-samenvattingen](#trace-summary-fields) ofwel [spans](#span-fields), beschreven aan
het einde van deze pagina.
## Een trace lokaliseren
Vind de performance-acties en error-incidenten waarin een trace voorkomt, over sites heen.
```shell Endpoint theme={null}
POST /api/v2/tracing/locator
```
De request body neemt `site_ids` (een string-array) en `trace_id` (een string). In
ruil ontvangt u een `TraceLocation` met `performance`-entries (`site_id`,
`namespace`, `action_name`) en `errors`-entries (`site_id`, `incident_number`,
`exception_name`).
## De spans van een trace ophalen
Retourneert elke span in een trace.
```shell Endpoint theme={null}
POST /api/v2/tracing/trace
```
De request body neemt `site_ids` (een string-array) en `trace_id` (een string),
en retourneert een array van [spans](#span-fields).
```json body.json theme={null}
{
"site_ids": ["YOUR-SITE-ID"],
"trace_id": "YOUR-TRACE-ID"
}
```
De eindpunten `POST /api/v2/tracing/trace/performance` en `POST /api/v2/tracing/trace/error`
retourneren de [spans](#span-fields) van een performance- of error-trace met behulp van
de [`TracesQuery`](#tracesquery)-body.
## Traces opsommen
Som performance- of error-traces op.
```shell Endpoints theme={null}
POST /api/v2/tracing/traces/performance
POST /api/v2/tracing/traces/errors
```
Beide nemen de [`TracesQuery`](#tracesquery)-body en retourneren een array van [trace-
samenvattingen](#trace-summary-fields).
```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" }
}
```
`pagination` neemt `per_page`, `order` en een `cursor`-sleutel. Stel `cursor` in op
`Time` om te pagineren op tracetijd of `Duration` om te pagineren op totale traceduur.
### TracesQuery
| Veld | Type | Vereist | Beschrijving |
| ------------- | ----------------- | ------- | ----------------------------------------------------------------- |
| `site_ids` | string\[] | Ja | Sites om op te vragen. |
| `pagination` | object | Ja | Paginatie-instellingen. Stel `cursor` in op `Time` of `Duration`. |
| `digests` | string\[] | Nee | Filter op trace-digests. |
| `action_name` | string | Nee | Filter op actienaam. |
| `namespace` | string | Nee | Filter op namespace. |
| `query` | string | Nee | Vrije-tekst zoekquery. |
| `duration` | number (ms) | Nee | Filter op minimale duur. |
| `from` | string (ISO 8601) | Nee | Startpunt van het tijdsbereik. |
| `to` | string (ISO 8601) | Nee | Eindpunt van het tijdsbereik. |
| `ttl` | number | Nee | Retentiegrens in seconden. |
## Performance-acties opsommen
Som performance-acties op met geaggregeerde metrics.
```shell Endpoint theme={null}
POST /api/v2/tracing/actions
```
De request body neemt `site_id`, `from`, `to` en de optionele filters `namespaces`
(array), `revision` en `action`. U krijgt een array van actie-rijen terug,
elk met `namespace`, `action`, `digest`, `mean` (ms), `throughput`,
`error_rate` (0–100) en `has_npo` (of er een N+1-query is gedetecteerd).
## Edges voor service-afhankelijkheden
Breng distributed tracing-relaties tussen acties en services in kaart.
```shell Endpoints theme={null}
POST /api/v2/tracing/action_edges
POST /api/v2/tracing/site_edges
```
`action_edges` retourneert de `upstream` (callers) en `downstream` (callees) edges
voor een gefocuste actie. De body neemt `site_id`, `namespace` (in
`"/"`-vorm, zoals `"PublicApi/web"`), `action`, `from` en
`to`.
`site_edges` retourneert `upstream`-, `downstream`- en `internal`-edges voor een gefocuste
site. De body neemt `site_id`, `from` en `to`.
Elke edge meldt de peer-`service`, het aantal verzoeken (`count`), `error_count`, `mean` (ms),
en `p_90`- / `p_95`-duren. Actie-edges bevatten ook de peer `namespace`,
`action`, span-soorten en `edge_type` (`SYNC` of `ASYNC`).
## Trage events
Analyseer trage operaties binnen traces, zoals trage databasequery's.
```shell Endpoints theme={null}
POST /api/v2/tracing/slow_events
POST /api/v2/tracing/slow_events/actions
```
`slow_events` retourneert geaggregeerde trage events. De body neemt `site_id`, `from`,
`to`, een optionele `span_kind`, `wanted_attributes`, `excluded_attributes` en een
`limit` (standaard 100). Elk resultaat heeft een `digest`, `count`, `mean` (ms),
`impact`-score en `attributes`.
`slow_events/actions` somt de acties op waarin een traag event voorkomt, op `digest`. De
body neemt `site_id`, `from`, `to` en `digest`. Elk resultaat heeft een
`action_name`, `namespace`, `count`, `trace_id` en `start_time`.
## Velden van trace-samenvattingen
De lijst-eindpunten retourneren trace-samenvattingen met deze velden:
| Veld | Type | Beschrijving |
| ------------- | ----------------- | ------------------------------------------------------ |
| `trace_id` | string | Identificator voor de hele trace. |
| `span_id` | string | Identificator voor de hoofdspan. |
| `site_id` | string | Site waar de trace bij hoort. |
| `namespace` | string | Namespace, zoals `web` of `background`. |
| `action_name` | string | Actienaam, zoals `POST /api/users`. |
| `revision` | string | Deploy-revisie die actief was bij vastlegging. |
| `time` | string (ISO 8601) | Wanneer de trace eindigde. |
| `duration` | number | Totale duur in milliseconden. |
| `tags` | object | Door gebruiker gedefinieerde tags uit span-attributen. |
| `has_npo` | boolean | Of er een N+1-query is gedetecteerd. |
## Span-velden
De trace-detail-eindpunten retourneren spans. Elke span bevat timing
(`start_time`, `end_time`, `duration` in ms), identiteit (`trace_id`, `span_id`,
`parent_span_id`, `digest`) en context (`service_name`, `namespace`,
`revision`, `action_name`, `span_name`, `span_kind`, `scope_name`,
`scope_version`). De status wordt gerapporteerd met `status_code` (zoals `OK` of `ERROR`)
en `status_message`.
Gestructureerde details worden geretourneerd als objecten en arrays: `resource_attributes` en
`span_attributes` (objects), `events` (met `events.timestamp`, `events.name`
en `events.attributes` arrays), en `links` (met `links.trace_id`,
`links.span_id`, `links.trace_state` en `links.attributes` arrays).
`subtrace_root` geeft aan of de span een aparte servicegrens begint.