App Environment Traces API

The App Environment Traces API lets you search and read the distributed traces (OpenTelemetry, stored in Tempo) of an app environment in Quave ONE. Use it to find which requests fail or are slow, and then open a trace to see every span with its timing, status and key attributes.

Make sure to read the Get Started document to understand how the API works.

Note: These endpoints accept only user tokens (not environment tokens).

Tracing must be released for the account by Quave ONE and enabled on the environment (see PATCH /app-env/tracing). Otherwise the endpoints answer 400 with Tracing not available or Tracing disabled.

Search Traces

Send a GET request to /api/public/v1/app-env/traces/search. The search always stays inside the environment, and every filter applies to the same span.

Parameters

Parameter	Type	Required	Default	Description
appEnvId or envName	String	Yes		Environment identifier (provide one or the other)
from	String	No	1 hour before to	Start time (ISO 8601)
to	String	No	now	End time (ISO 8601)
status	String	No	any	error, ok or unset
minDuration	String	No		Minimum span duration, e.g. 500ms, 2s, 1m
spanName	String	No		Case-sensitive substring of the span name
httpRoute	String	No		Exact http.route, e.g. /api/orders/:id
minHttpStatusCode	Number	No		Minimum http.response.status_code, e.g. 500
kind	String	No	any	server, client, internal, producer or consumer
tableType	String	No	traces	traces (one row per trace) or spans (the matching spans)
limit	Number	No	20	Maximum traces to search for (max 50)

Windows longer than 6 hours are shortened to the most recent 6 hours and the response reports windowClamped: true. Prefer short windows: long searches are expensive for the tracing backend.

Example

curl -H "Authorization: Bearer $QUAVE_ONE_TOKEN" \
  "https://api.quave.one/api/public/v1/app-env/traces/search?envName=my-app-production&status=error&minDuration=500ms"

Response

{
  "appEnvId": "abc123",
  "from": "2026-09-10T19:35:00.000Z",
  "to": "2026-09-10T20:35:00.000Z",
  "windowClamped": false,
  "tableType": "traces",
  "limit": 20,
  "query": "{ resource.quave.appenv.id = \"abc123\" && status = error && duration >= 500ms }",
  "count": 1,
  "results": [
    {
      "traceId": "7a26b531f46d143118b4772d91ec3cfa",
      "startTime": "2026-09-10T20:35:00.260Z",
      "durationMs": 873,
      "matchedSpans": [
        {
          "spanId": "7440a6a696a73ca2",
          "startTime": "2026-09-10T20:35:00.260Z",
          "name": "GET /api/orders/:id",
          "status": "error",
          "durationMs": 873.2
        }
      ]
    }
  ]
}

durationMs is the duration of the whole trace; matchedSpans lists the spans of this environment that matched the filters. With tableType=spans, each result is a matching span with traceId, spanId, startTime, name, status and durationMs.

Get a Trace

Send a GET request to /api/public/v1/app-env/traces/detail.

Parameters

Parameter	Type	Required	Default	Description
appEnvId or envName	String	Yes		Environment identifier (provide one or the other)
traceId	String	Yes		Hexadecimal trace ID (up to 32 characters)
maxSpans	Number	No	200	Maximum spans to return, earliest first (max 500)

Response

{
  "appEnvId": "abc123",
  "traceId": "7a26b531f46d143118b4772d91ec3cfa",
  "startTime": "2026-09-10T20:35:00.260Z",
  "durationMs": 873.2,
  "services": ["my-app"],
  "spanCount": 4,
  "appEnvSpanCount": 4,
  "errorSpanCount": 1,
  "truncated": false,
  "spans": [
    {
      "spanId": "7440a6a696a73ca2",
      "parentSpanId": null,
      "service": "my-app",
      "name": "GET /api/orders/:id",
      "kind": "server",
      "status": "error",
      "startOffsetMs": 0,
      "durationMs": 873.2,
      "statusMessage": "Order lookup failed",
      "attributes": {
        "http.route": "/api/orders/:id",
        "http.response.status_code": 500
      },
      "events": [
        {
          "name": "exception",
          "time": "2026-09-10T20:35:01.100Z",
          "attributes": { "exception.message": "Timeout" }
        }
      ]
    }
  ]
}

• Use parentSpanId to rebuild the span tree; startOffsetMs is relative to the start of the trace.
• attributes keeps diagnostic keys only (http.*, url.*, db.*, rpc.*, messaging.*, peer.*, server.*, net.*, error.*, exception.*), up to 30 per span and 10 per event. Keys that commonly carry credentials or bound values (headers, gRPC metadata, cookies, authorization, tokens, passwords, secrets, connection strings, API keys, db.query.parameter.*) are never returned. Credentials embedded in URIs are redacted in every value and in statusMessage; URL query parameter values and fragments are redacted; long values are truncated.
• Large traces are cut when the spans reach about 1 MB of JSON, and truncated is true (also when maxSpans is reached).
• Spans of other environments of the account that are part of the same trace only include spanId, parentSpanId, startOffsetMs and durationMs, with otherAppEnv: true. services and errorSpanCount only count this environment's spans.
• The endpoint answers 404 when the trace does not exist, is outside the retention period, or has no span from this environment.