Traces
List traces and read one with every span, from the browser request to the database calls.
A trace is one request and everything it caused. The browser SDK starts it and sends the W3C traceparent
header; the server SDK or your OpenTelemetry exporter adds the server spans under the same trace id.
Traces are kept as long as events (see retention).
The trace object
Fields
-
idstring optionalThe W3C trace id, 32 hex characters.
-
started_attimestamp optional -
duration_msinteger optionalFrom the start of the first span to the end of the last.
-
namestring optionalThe root span’s name, usually
METHOD route. -
methodstring or null optional -
routestring or null optionalThe API route, with ids replaced.
-
status_codeinteger or null optionalThe HTTP status the root answered.
0when the browser got no answer. -
failedboolean optional -
partialboolean optionaltruewhen the request never finished. -
servicesarray of string optionalThe services that ran spans, and the ones they called (
peer.service). The browser isbrowser. -
span_countinteger optional -
dropped_spansinteger optionalSpans beyond the 500 kept per trace.
-
session_idstring or null optional -
problem_idstring or null optionalThe problem this trace is an occurrence of.
-
environmentstring optional -
releasestring or null optional
The span object
One step of a trace. The same shape whatever sent it, a Sypnia SDK or an OpenTelemetry exporter.
Fields
-
idstring optional16 hex characters.
-
parent_idstring or null optionalThe span that caused this one.
nullfor the root. -
namestring optionalWhat the step is:
POST /api/checkout,SELECT carts,createPayment. -
kindstring optionalbrowser: a request as the browser saw it.server: a request handled by a service.db: a database call.http: an outgoing HTTP call.internal: anything else. -
servicestring optionalWhich service ran it (
service.name). -
start_offset_msinteger optionalStart, in milliseconds from the start of the trace.
-
duration_msinteger optional -
statusstring optionalrunningonly in a partial trace. One of:ok,error,running. -
attributesobject optionalDetails, with OpenTelemetry’s names:
http.response.status_code,db.system.name,error.type. Up to 64, values up to 256 characters.
List traces
/v1/traces EngineCloud Traces that started in the time range, without their spans. A trace is failed when any of its spans has status error, which means a call that got no answer, answered 400, answered 500 or above, or threw.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
sincestring optionalOnly traces that started after this moment.
Default:
24h -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
-
routestring, up to 500 characters optionalOnly traces whose root is this API route (
/api/checkout,/api/orders/:id). -
methodstring optionalOnly traces whose root has this HTTP method. One of:
GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS. -
failedboolean optionaltruereturns only failed traces,falseonly successful ones. -
min_duration_msinteger, at least 0 optionalOnly traces at least this long.
-
sessionstring optionalOnly traces of this session.
-
servicestring, up to 80 characters optionalOnly traces with a span from this service (
service.name). -
releasestring optionalOnly traces on this release version.
-
sortstring optionalrecentorslowest.Default:
recent -
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/traces?route=/api/checkout&failed=true" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"data": [
{
"id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
"started_at": "2026-03-12T10:31:43Z",
"duration_ms": 3870,
"name": "POST /api/checkout",
"method": "POST",
"route": "/api/checkout",
"status_code": 400,
"failed": true,
"partial": false,
"services": [
"browser",
"shop-api",
"payments"
],
"span_count": 4,
"dropped_spans": 0,
"session_id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"problem_id": "prb_8f3k2m9x4q7w",
"environment": "production",
"release": "4f2a91c"
}
],
"next_cursor": null
}Get a trace
/v1/traces/{trace_id} EngineCloud The trace with every span, ordered by start. Spans form a tree through parent_id; the root has null.
partial is true when the request never finished (it was killed by a timeout): the spans are the ones that
had been reported, and those still running have status: running.
Path parameters
-
trace_idstring requiredThe trace id, 32 hex characters.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl "https://api.sypnia.com/v1/traces/7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
"started_at": "2026-03-12T10:31:43Z",
"duration_ms": 3870,
"name": "POST /api/checkout",
"method": "POST",
"route": "/api/checkout",
"status_code": 400,
"failed": true,
"partial": false,
"services": [
"browser",
"shop-api",
"payments"
],
"span_count": 4,
"dropped_spans": 0,
"session_id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
"problem_id": "prb_8f3k2m9x4q7w",
"environment": "production",
"release": "4f2a91c",
"spans": [
{
"id": "0f1e2d3c4b5a6978",
"parent_id": null,
"name": "POST /api/checkout",
"kind": "browser",
"service": "browser",
"start_offset_ms": 0,
"duration_ms": 3870,
"status": "error",
"attributes": {
"http.request.method": "POST",
"http.response.status_code": 400,
"error.type": "amount_required"
}
},
{
"id": "a1b2c3d4e5f60718",
"parent_id": "0f1e2d3c4b5a6978",
"name": "POST /api/checkout",
"kind": "server",
"service": "shop-api",
"start_offset_ms": 14,
"duration_ms": 3842,
"status": "error",
"attributes": {
"http.route": "/api/checkout",
"http.response.status_code": 400
}
},
{
"id": "b2c3d4e5f6071829",
"parent_id": "a1b2c3d4e5f60718",
"name": "SELECT carts",
"kind": "db",
"service": "shop-api",
"start_offset_ms": 21,
"duration_ms": 12,
"status": "ok",
"attributes": {
"db.system.name": "postgresql",
"db.operation.name": "SELECT",
"db.collection.name": "carts"
}
},
{
"id": "c3d4e5f60718293a",
"parent_id": "a1b2c3d4e5f60718",
"name": "createPayment",
"kind": "http",
"service": "shop-api",
"start_offset_ms": 46,
"duration_ms": 3790,
"status": "error",
"attributes": {
"peer.service": "payments",
"server.address": "api.payments.example",
"http.request.method": "POST",
"http.response.status_code": 400,
"error.type": "amount_required"
}
}
]
}Errors
- 404
not_foundNo trace has this id in the project.
- 410
expiredThe trace is older than the project’s retention.
The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.