# Traces

> List traces and read one with every span, from the browser request to the database calls.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/traces/

For agents: Reference of the Traces endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

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](https://docs.sypnia.com/api/errors-limits-pagination#retention)).

## The trace object

**Fields:**

- `id` (string, optional): The W3C trace id, 32 hex characters.
- `started_at` (timestamp, optional)
- `duration_ms` (integer, optional): From the start of the first span to the end of the last.
- `name` (string, optional): The root span's name, usually `METHOD route`.
- `method` (string or null, optional)
- `route` (string or null, optional): The API route, with ids replaced.
- `status_code` (integer or null, optional): The HTTP status the root answered. `0` when the browser got no answer.
- `failed` (boolean, optional)
- `partial` (boolean, optional): `true` when the request never finished.
- `services` (array of string, optional): The services that ran spans, and the ones they called (`peer.service`). The browser is `browser`.
- `span_count` (integer, optional)
- `dropped_spans` (integer, optional): Spans beyond the 500 kept per trace.
- `session_id` (string or null, optional)
- `problem_id` (string or null, optional): The problem this trace is an occurrence of.
- `environment` (string, optional)
- `release` (string 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:**

- `id` (string, optional): 16 hex characters.
- `parent_id` (string or null, optional): The span that caused this one. `null` for the root.
- `name` (string, optional): What the step is: `POST /api/checkout`, `SELECT carts`, `createPayment`.
- `kind` (string, optional): `browser`: 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.
- `service` (string, optional): Which service ran it (`service.name`).
- `start_offset_ms` (integer, optional): Start, in milliseconds from the start of the trace.
- `duration_ms` (integer, optional)
- `status` (string, optional): `running` only in a partial trace. One of: `ok`, `error`, `running`.
- `attributes` (object, optional): Details, with OpenTelemetry's names: `http.response.status_code`, `db.system.name`, `error.type`. Up to 64, values up to 256 characters.

## List traces

`GET /v1/traces` \[Engine, Cloud]

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.

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The 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`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `24h`): Only traces that started after this moment.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `route` (string, up to 500 characters, optional): Only traces whose root is this API route (`/api/checkout`, `/api/orders/:id`).
- `method` (string, optional): Only traces whose root has this HTTP method. One of: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
- `failed` (boolean, optional): `true` returns only failed traces, `false` only successful ones.
- `min_duration_ms` (integer, at least 0, optional): Only traces at least this long.
- `session` (string, optional): Only traces of this session.
- `service` (string, up to 80 characters, optional): Only traces with a span from this service (`service.name`).
- `release` (string, optional): Only traces on this release version.
- `sort` (string, optional, default `recent`): `recent` or `slowest`.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/traces?route=/api/checkout&failed=true" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "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

`GET /v1/traces/{trace_id}` \[Engine, Cloud]

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

**Authentication:** API token (`read`)

**Path parameters:**

- `trace_id` (string, required): The trace id, 32 hex characters.

**Query parameters:**

- `project` (string, optional): The 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:**

```bash
curl "https://api.sypnia.com/v1/traces/7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "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_found`: No trace has this id in the project.
- `410` `expired`: The trace is older than the project's retention.

The errors every endpoint can answer (`401`, `403`, `429`, `500`, `503`) are on [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination).
