Skip to content

Traces API

The Traces API exposes execution traces recorded by the gateway for individual inference requests. Gateway traces capture the same step-by-step pipeline detail as Playground traces and are linked to log entries via the trace_id field.

Base URL: https://<your-gateway-host>/admin/v1

GET /gateways/{id}/traces

Returns recent gateway-level execution traces for a gateway, ordered newest-first.

curl "https://<your-gateway-host>/admin/v1/gateways/gw_xyz789/traces?limit=50"

Query parameters

Parameter Type Default Description
limit integer 50 Maximum number of traces to return. Capped at 200.

Response

An array of trace summary objects:

Field Type Description
id string Trace UUID. Use with GET /traces/{id} to fetch full detail.
model string Model used for this request.
created_at integer Trace start time as Unix seconds.
completed_at integer | null Trace end time as Unix seconds. null if still running.
status string One of running, done, error.
error string | null Error message if status is error.
source string Always gateway for traces returned by this endpoint.

Example response

[
  {
    "id": "trc_abc123",
    "model": "gpt-4o",
    "created_at": 1742547600,
    "completed_at": 1742547601,
    "status": "done",
    "error": null,
    "source": "gateway"
  },
  {
    "id": "trc_def456",
    "model": "claude-opus-4-6",
    "created_at": 1742547580,
    "completed_at": null,
    "status": "running",
    "error": null,
    "source": "gateway"
  }
]

GET /traces/{id}

Required role: tenant admin (or platform admin). The full trace detail includes prompt and model-response content, so single-trace reads are restricted to tenant admins; the same applies to the equivalent GET /playground/trace/{id}.

Fetches the full detail of any trace — gateway or Playground — by its ID. Returns the trace metadata alongside an ordered list of pipeline steps.

curl "https://<your-gateway-host>/admin/v1/traces/trc_abc123"

Response structure

{
  "trace": { ...TraceObject },
  "steps": [ ...StepObject ]
}

TraceObject fields

Field Type Description
id string Trace UUID.
gateway_id string UUID of the gateway the traced request ran on.
conversation_id string | null UUID of the conversation the trace belongs to, when the request came from a conversation; null otherwise.
model string Model used.
created_at integer Trace start time as Unix seconds.
completed_at integer | null Trace end time. null if still running.
status string One of running, done, error.
error string | null Error message, if any.
source string gateway or playground.

StepObject fields

Field Type Description
id integer Auto-increment step id.
trace_id string UUID of the trace this step belongs to.
seq integer Step sequence number (1-based, ascending).
step string Step name identifying the pipeline stage (e.g. request_received, routing_applied, guardrail_result, upstream_request, upstream_response, upstream_error, tool_call, tool_result, rag_rank, response_delivered).
data object Step-specific structured data (decoded from JSON). Content varies by step type.
ts integer Step timestamp as Unix seconds.

A rag_rank step is recorded whenever the knowledge-search tool runs. Its data reports the retrieval ranking and the optional cross-encoder rerank stage: mode (dormant when no reranker is configured, reranked when the reranker reordered the results, or fallback when a configured reranker was unavailable and the fused order was kept), configured (whether a reranker model is set), fused_n (candidate passages after hybrid fusion), kept (passages served after any rerank trim), and sent (passages sent to the reranker). The ranked document identifiers (order) are included only when the gateway enables tracing.include_bodies.

Example response

{
  "trace": {
    "id": "trc_abc123",
    "model": "gpt-4o",
    "created_at": 1742547600,
    "completed_at": 1742547601,
    "status": "done",
    "error": null,
    "source": "gateway"
  },
  "steps": [
    {
      "seq": 1,
      "step": "request_received",
      "data": { "tenant": "myapp", "model": "gpt-4o" }
    },
    {
      "seq": 2,
      "step": "routing_applied",
      "data": { "provider": "openai", "model": "gpt-4o" }
    },
    {
      "seq": 3,
      "step": "upstream_request",
      "data": {
        "provider": "openai",
        "model": "gpt-4o"
      }
    },
    {
      "seq": 4,
      "step": "upstream_response",
      "data": {
        "latency_ms": 780,
        "status": 200
      }
    },
    {
      "seq": 5,
      "step": "response_delivered",
      "data": {
        "input_tokens": 512,
        "output_tokens": 128
      }
    }
  ]
}

💡 Note: Returns 404 if no trace with the given ID exists.

Linking traces to log entries

When gateway tracing is enabled, each request log entry includes a trace_id field. Use it to look up the corresponding full trace:

# 1. Find the trace_id from the request-log LIST (the single-log GET omits trace_id)
curl "https://<your-gateway-host>/admin/v1/logs?limit=20"
# → [ { "id": "log_abc789", "trace_id": "trc_abc123", ... }, ... ]

# 2. Fetch the full trace
curl "https://<your-gateway-host>/admin/v1/traces/trc_abc123"

💡 Note: When trace_id is null in a log entry, gateway tracing was not active for that request.

See also