Traces
Retrieve and query causal traces via the Incidentary REST API
Traces
A trace is the causal chain of events captured by the SDK across one or more services. Traces are stored automatically when the SDK flushes on alert or on a configurable flush interval.
Get Trace
GET /v1/traces/:idResponse:
{
"id": "trc_01HABC",
"service": "order-service",
"rootSpan": {
"id": "spn_01H001",
"name": "handle-request",
"startedAt": "2026-03-01T02:13:50Z",
"endedAt": "2026-03-01T02:13:51.240Z",
"durationMs": 1240,
"events": [
{
"name": "order.validation.started",
"timestamp": "2026-03-01T02:13:50.100Z",
"attributes": {}
}
]
},
"spans": [...],
"capturedAt": "2026-03-01T02:14:00Z",
"preArmWindowMs": 30000
}List Spans
GET /v1/traces/:id/spansReturns all spans in the trace in topological order (root first, children following).
Response:
{
"data": [
{
"id": "spn_01H001",
"parentId": null,
"name": "handle-request",
"service": "order-service",
"startedAt": "2026-03-01T02:13:50Z",
"endedAt": "2026-03-01T02:13:51.240Z",
"durationMs": 1240,
"status": "ok",
"events": [...]
},
{
"id": "spn_01H002",
"parentId": "spn_01H001",
"name": "db.query",
"service": "order-service",
"startedAt": "2026-03-01T02:13:50.200Z",
"endedAt": "2026-03-01T02:13:50.850Z",
"durationMs": 650,
"status": "ok",
"events": []
}
]
}List Events for a Span
GET /v1/traces/:traceId/spans/:spanId/eventsReturns all causal events emitted within a span, ordered by timestamp.
Search Traces
GET /v1/traces?service=order-service&from=2026-03-01T00:00:00ZQuery Parameters:
| Param | Type | Description |
|---|---|---|
service | string | Filter by service name |
from | ISO 8601 | Start of time range |
to | ISO 8601 | End of time range |
incidentId | string | Return traces linked to a specific incident |
cursor | string | Pagination cursor |
limit | integer | Max 100, default 20 |