Docs

Traces

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

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The trace object
  2. The span object
  3. List traces
  4. Get a trace

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

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

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Only traces that started after this moment.

    Default: 24h

  • 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

    recent or slowest.

    Default: recent

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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

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

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

Response200

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

  • 404not_found

    No trace has this id in the project.

  • 410expired

    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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close