GET /v8/traces/{traceId} — Inspect Mission Execution Trace

The GET /v8/traces/{traceId} endpoint returns a detailed, redacted causal trace for a specific mission execution unit. Traces give you deep visibility into exactly what the agent did during a step: the inputs it received, the tool calls it made, the outputs it produced, and the wall-clock timing for each operation. This is your primary tool for debugging unexpected agent behaviour, auditing policy decisions, and optimising resource budgets. Sensitive fields are redacted before the trace leaves the gateway — credentials, tokens, and other secret values are never exposed in trace data.

You can find traceId values in the data payload of mission.step.completed and mission.step.started events emitted by the Mission Events stream. Each step event includes a traceId field that maps directly to this endpoint.

Endpoint

GET /v8/traces/{traceId}

Required scope: traces:read Required headers:

Header	Description
`Authorization`	`Bearer <access_token>` — short-lived Ed25519 delegated OAuth token

Path Parameters

traceId

string

required

The unique identifier of the trace to retrieve. Must match the pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$ and be between 1 and 256 characters. Trace IDs are surfaced in mission event payloads and in the steps array of a MissionProjection.Example: trc_018e2f3a.step_3.exec

Example Request

curl https://your-gateway.example/v8/traces/trc_018e2f3a.step_3.exec \
  -H "Authorization: Bearer $PRAXA_ACCESS_TOKEN"

import { PraxaClient } from "@praxa/sdk";

const client = new PraxaClient({ accessToken: process.env.PRAXA_ACCESS_TOKEN });

const trace = await client.getTrace("trc_018e2f3a.step_3.exec");

console.log(trace);

Response

Status: 200 OK The response body is a redacted causal trace object. The exact schema may evolve as the platform adds richer observability, but the following fields are always present.

traceId

string

required

The unique identifier for this trace. Matches the path parameter you supplied.

missionRunId

string (UUID)

required

The runId of the mission this trace belongs to. Use this to correlate traces back to the originating mission.

stepId

string

required

The identifier of the mission step this trace captures.

startedAt

string (ISO 8601)

required

UTC timestamp of when this step began executing.

completedAt

string (ISO 8601)

UTC timestamp of when this step finished. Absent if the step did not complete (e.g., it was cancelled mid-execution).

elapsedMs

integer

Total wall-clock duration of the step in milliseconds.

steps

array

required

Ordered list of operations performed during this trace. Each element describes a single operation — a reasoning observation, a tool call, or a sub-step — with its own timing and I/O details.

Show Operation object fields

operationId

string

Unique identifier for this operation within the trace.

kind

string

The type of operation: "observation", "tool-call", "sub-step", or "branch".

toolCallId

string

Present when kind is "tool-call". Identifies the specific capability or tool that was invoked.

input

object

The redacted input passed to this operation. Sensitive values are replaced with [REDACTED].

output

object

The redacted output produced by this operation.

startedAt

string (ISO 8601)

When this individual operation began.

elapsedMs

integer

Duration of this individual operation in milliseconds.

Example 200 response

{
  "traceId": "trc_018e2f3a.step_3.exec",
  "missionRunId": "018e2f3a-7c14-7000-b1e2-4d3f8a20c911",
  "stepId": "step_3",
  "startedAt": "2025-07-11T10:04:22.100Z",
  "completedAt": "2025-07-11T10:04:24.853Z",
  "elapsedMs": 2753,
  "steps": [
    {
      "operationId": "op_1",
      "kind": "tool-call",
      "toolCallId": "praxa.web-search.v2",
      "input": { "query": "EMEA SaaS revenue Q2 2025" },
      "output": { "results": "[REDACTED: 3 items]" },
      "startedAt": "2025-07-11T10:04:22.300Z",
      "elapsedMs": 1840
    },
    {
      "operationId": "op_2",
      "kind": "observation",
      "input": { "summary": "Retrieved 3 relevant articles" },
      "output": { "decision": "Proceed to summarisation step" },
      "startedAt": "2025-07-11T10:04:24.140Z",
      "elapsedMs": 712
    }
  ]
}

Error Responses

All errors follow RFC 9457 Problem Details.

HTTP Status	Typical cause
`401 Unauthorized`	Missing or expired `Authorization` bearer token
`403 Forbidden`	Token lacks `traces:read` scope
`404 Not Found`	No trace exists with the given `traceId` under your principal’s policy scope

SDK Equivalent

const trace = await client.getTrace(traceId);

Parameter	Type	Description
`traceId`	`string`	Identifier of the trace to retrieve

Returns: Promise<JsonValue>

Overview

Missions

Capabilities & Memory

Skills & Traces

Context & World Model

GET /v8/traces/{traceId} — Inspect Mission Execution Trace

Endpoint

Path Parameters

Example Request

Response

Error Responses

SDK Equivalent

​Endpoint

​Path Parameters

​Example Request

​Response

​Error Responses

​SDK Equivalent

Endpoint

Path Parameters

Example Request

Response

Error Responses

SDK Equivalent