API reference
Traces
One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.
Endpoints
8
POST
/api/v1/otlp/v1/traces
Agent Token
Ingest OTLP JSON traces
traces:write
/api/v1/otlp/v1/traces
Agent Token
Ingest OTLP JSON traces
Description
OTLP/HTTP JSON trace receiver. Set the exporter base URL to /api/v1/otlp; exporters append /v1/traces. Requires traces:write machine credentials; protobuf and gRPC are not served by this route. Supports identity and gzip encoding with an 8 MiB encoded/decoded body limit and at most 512 spans per request. Invalid spans produce HTTP 200 partialSuccess; rejectedSpans is a decimal string. A quota failure rolls back the whole batch with 429 and Retry-After; existing trace IDs can retry at the quota cap. Stored external_trace_id is otlp:<traceId>, and source_event_id is the original spanId. Trace/span/parent IDs and nanosecond timestamps are retained in metadata; duration_ms is derived without claiming trace completion. Trace state stays running because one export does not establish completeness; replayable is false. Only selected resource/GenAI attributes survive. Span events, links, bodies and free-form status messages are dropped. Names and stored metadata use credential redaction. This route cannot write engagement-managed traces. All error responses use OTLP Status JSON {code, message}.
Auth
Agent TokenRequired Scopes
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| resourceSpans | array<object> | No | OTLP resource spans JSON object |
Responses
200
Accepted; partialSuccess is returned when spans were rejected
Accepted; partialSuccess is returned when spans were rejected
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| partialSuccess | object | No | OTLP partial success counts |
| partialSuccess.errorMessage | string | Yes | Safe validation summary |
| partialSuccess.rejectedSpans | string | Yes | Rejected span count (protobuf int64 decimal string) |
Example
{}
400
Invalid OTLP JSON, container shape, or malformed gzip
Invalid OTLP JSON, container shape, or malformed gzip
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| code | integer | Yes | OTLP Status code |
| message | string | Yes | Safe error message |
401
Invalid or missing token
Invalid or missing token
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| code | integer | Yes | OTLP Status code |
| message | string | Yes | Safe error message |
403
Missing traces:write scope or an engagement-managed trace
Missing traces:write scope or an engagement-managed trace
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| code | integer | Yes | OTLP Status code |
| message | string | Yes | Safe error message |
413
Body exceeds 8 MiB or batch exceeds 512 spans
Body exceeds 8 MiB or batch exceeds 512 spans
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| code | integer | Yes | OTLP Status code |
| message | string | Yes | Safe error message |
415
Unsupported content type or encoding; use application/json with identity or gzip
Unsupported content type or encoding; use application/json with identity or gzip
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| code | integer | Yes | OTLP Status code |
| message | string | Yes | Safe error message |
429
Quota or rate limit exceeded; Retry-After is returned
Quota or rate limit exceeded; Retry-After is returned
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| code | integer | Yes | OTLP Status code |
| message | string | Yes | Safe error message |
503
Quota state unavailable; retry with backoff
Quota state unavailable; retry with backoff
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| code | integer | Yes | OTLP Status code |
| message | string | Yes | Safe error message |
POST
/api/v1/traces
Agent Token
Create a new trace
traces:write
/api/v1/traces
Agent Token
Create a new trace
Description
Ingests a trace for observability. A successful response confirms the trace, events, and durable projection jobs committed; search indexing, failure grouping, realtime notifications, and webhook staging run asynchronously and are eventually consistent. When `external_trace_id` is set, ingest is idempotent on `(workspace_id, external_trace_id)`: a retry finds the existing row instead of inserting a duplicate. The same request may include up to 50 event objects. Find-or-create, event insertion, and optional finalization commit together; validation failure leaves the trace and events unchanged. A non-`running` `status` finalizes the trace. To finish a running trace, POST again with the same `external_trace_id`, its name, and status `ok`, `error`, or `partial`; omit `events` in that second request. Repeated events append again unless each has a stable `source_event_id`. An identical completed-state retry keeps its end time and finalization identity; fresh late events still append. Payload or timing corrections within the same terminal identity emit trace.updated without recounting failures. A changed status or explicit failure signature is a new finalization transition. Workspace, service-agent, and workflow bindings cannot be changed by retries. The write is refused with 429 `quota-exceeded` when the workspace `traces_per_month` quota is exhausted.
Auth
Agent TokenRequired Scopes
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Human-readable trace name |
| status | string (running, ok, error, partial) | No | Initial status. Values other than running finalize the trace after ingest. |
| events | array<object> | No | Optional array of at most 50 events. Each object requires event_type and name. |
| events[].name | string | Yes | Human-readable event name (required) |
| events[].status | string (ok, error, pending) | No | Event status |
| events[].metadata | object | No | Optional event metadata |
| events[].started_at | datetime (ISO 8601) | No | Event start time |
| events[].error_payload | object | No | Optional error payload |
| events[].event_type | string | Yes | Event type label (required) |
| events[].duration_ms | integer | No | Duration in milliseconds |
| events[].input_payload | object | No | Optional input payload |
| events[].output_payload | object | No | Optional output payload |
| events[].cost | number | No | Cost attributed to the event |
| events[].ended_at | datetime (ISO 8601) | No | Event end time |
| events[].latency_ms | integer | No | Latency in milliseconds |
| events[].parent_event_id | string | No | Parent event UUID when nested |
| events[].source_event_id | string | No | Caller-supplied id; unique per trace and skipped on replay |
| events[].span_kind | string | No | Span kind (defaults to step) |
| metadata | object | No | Additional trace metadata |
| summary | string | No | Optional operator summary |
| environment | string | No | Environment label (defaults to production) |
| service_agent_id | string | No | Optional service-agent UUID that owns this execution |
| error_payload | object | No | Optional error payload |
| workflow_target_id | string | No | Optional workflow target UUID |
| input_payload | object | No | Optional input payload |
| output_payload | object | No | Optional output payload |
| external_trace_id | string | No | Caller correlation id. Combined with workspace_id this is the ingest idempotency key. |
| trace_type | string (runtime, eval, replay) | No | Type of trace |
| workflow_version_id | string | No | Optional workflow version UUID |
Responses
201
Trace created or the existing idempotent row after find-or-start
Returns: TraceSummary
Trace created or the existing idempotent row after find-or-start
Returns: TraceSummary
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Trace UUID |
| name | string | Yes | Human-readable trace name |
| status | string (running, ok, error, partial) | Yes | Trace execution status |
| started_at | datetime (ISO 8601) | Yes | Trace start time |
| request_id | string | No | Internal request identifier |
| inserted_at | datetime (ISO 8601) | Yes | Record insertion timestamp |
| updated_at | datetime (ISO 8601) | Yes | Record update timestamp |
| environment | string | No | Exact environment label captured at ingest |
| service_agent | object | No | Associated service agent summary |
| service_agent.id | string | Yes | Service agent UUID |
| service_agent.name | string | Yes | Service agent name |
| workflow_target | object | No | Associated workflow target summary |
| workflow_target.id | string | Yes | Workflow target UUID |
| workflow_target.name | string | Yes | Workflow target name |
| duration_ms | integer | No | Trace duration in milliseconds |
| ended_at | datetime (ISO 8601) | No | Trace end time |
| external_trace_id | string | No | External trace identifier from the caller |
| last_activity_at | datetime (ISO 8601) | No | Last observed activity time |
| total_cost | number | No | Accumulated cost across the trace |
| trace_type | string (runtime, eval, replay) | Yes | Trace category |
| workflow_version | object | No | Associated workflow version summary |
| workflow_version.id | string | Yes | Workflow version UUID |
| workflow_version.label | string | Yes | Workflow version label |
Example
{
"duration_ms": 3200,
"ended_at": "2026-03-12T08:45:03Z",
"environment": "production",
"external_trace_id": "trace-checkout-443",
"id": "6646e3ff-8f2f-4204-ad5c-f4ebc1830f9e",
"inserted_at": "2026-03-12T08:45:03Z",
"last_activity_at": "2026-03-12T08:45:03Z",
"name": "checkout runtime trace",
"request_id": "req-01HQ5PX7P7F4",
"service_agent": {
"id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
"name": "payments-agent"
},
"started_at": "2026-03-12T08:45:00Z",
"status": "ok",
"total_cost": 0.12,
"trace_type": "runtime",
"updated_at": "2026-03-12T08:45:03Z",
"workflow_target": {
"id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
"name": "checkout-api"
},
"workflow_version": {
"id": "d0b91d0c-0f4b-4a28-8d9d-ccf0c427d6e8",
"label": "v2026.03.12"
}
}
401
Invalid or missing token
Invalid or missing token
413
More than 50 events
More than 50 events
422
Validation error on the trace or an included event
Validation error on the trace or an included event
429
Plan quota exceeded. Problem type https://robotscenter.net/problems/quota-exceeded with extra.resource traces_per_month.
Plan quota exceeded. Problem type https://robotscenter.net/problems/quota-exceeded with extra.resource traces_per_month.
POST
/api/v1/traces/:trace_id/events
Agent Token
Add events to a trace
traces:write
/api/v1/traces/:trace_id/events
Agent Token
Add events to a trace
Description
Atomically appends up to 50 event objects to an existing trace. Each event requires event_type and name. Optional source_event_id is unique per trace and makes a retry a no-op for that event.
Auth
Agent TokenRequired Scopes
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| events | array<object> | Yes | Up to 50 event objects to append. Each requires event_type and name. |
| events[].name | string | Yes | Human-readable event name (required) |
| events[].status | string (ok, error, pending) | No | Event status |
| events[].metadata | object | No | Optional event metadata |
| events[].started_at | datetime (ISO 8601) | No | Event start time |
| events[].error_payload | object | No | Optional error payload |
| events[].event_type | string | Yes | Event type label (required) |
| events[].duration_ms | integer | No | Duration in milliseconds |
| events[].input_payload | object | No | Optional input payload |
| events[].output_payload | object | No | Optional output payload |
| events[].cost | number | No | Cost attributed to the event |
| events[].ended_at | datetime (ISO 8601) | No | Event end time |
| events[].latency_ms | integer | No | Latency in milliseconds |
| events[].parent_event_id | string | No | Parent event UUID when nested |
| events[].source_event_id | string | No | Caller-supplied id; unique per trace and skipped on replay |
| events[].span_kind | string | No | Span kind (defaults to step) |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| trace_id | path | string | Yes | Trace UUID |
Responses
200
Events added
Events added
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| inserted | integer | Yes | Number of events written by this request |
Example
{
"inserted": 2
}
404
Trace not found
Trace not found
413
More than 50 events
More than 50 events
422
An event is missing event_type or name, or failed validation
An event is missing event_type or name, or failed validation
POST
/api/v1/traces/:trace_id/spans/batch
Agent Token
Add span events to a trace (batch alias)
traces:write
/api/v1/traces/:trace_id/spans/batch
Agent Token
Add span events to a trace (batch alias)
Description
Backwards-compatible batch ingestion alias for trace events. Same contract as POST /api/v1/traces/:trace_id/events: at most 50 event objects, each requiring event_type and name, and the response is {inserted: count}.
Auth
Agent TokenRequired Scopes
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| events | array<object> | Yes | Up to 50 event objects to append. Each requires event_type and name. |
| events[].name | string | Yes | Human-readable event name (required) |
| events[].status | string (ok, error, pending) | No | Event status |
| events[].metadata | object | No | Optional event metadata |
| events[].started_at | datetime (ISO 8601) | No | Event start time |
| events[].error_payload | object | No | Optional error payload |
| events[].event_type | string | Yes | Event type label (required) |
| events[].duration_ms | integer | No | Duration in milliseconds |
| events[].input_payload | object | No | Optional input payload |
| events[].output_payload | object | No | Optional output payload |
| events[].cost | number | No | Cost attributed to the event |
| events[].ended_at | datetime (ISO 8601) | No | Event end time |
| events[].latency_ms | integer | No | Latency in milliseconds |
| events[].parent_event_id | string | No | Parent event UUID when nested |
| events[].source_event_id | string | No | Caller-supplied id; unique per trace and skipped on replay |
| events[].span_kind | string | No | Span kind (defaults to step) |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| trace_id | path | string | Yes | Trace UUID |
Responses
200
Events added
Events added
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| inserted | integer | Yes | Number of events written by this request |
Example
{
"inserted": 2
}
404
Trace not found
Trace not found
413
More than 50 events
More than 50 events
422
An event is missing event_type or name, or failed validation
An event is missing event_type or name, or failed validation
GET
/api/v1/traces/:id
Agent Token
Get a trace (machine)
traces:read
/api/v1/traces/:id
Agent Token
Get a trace (machine)
Description
Returns the detail payload for a workspace trace. Requires traces:read. The body is redacted input/output/error/metadata, redaction_applied, events (including source_event_id), and optional failure_group. This is not a TraceSummary.
Auth
Agent TokenRequired Scopes
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Trace UUID |
Responses
200
Trace detail
Returns: Trace
Trace detail
Returns: Trace
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Trace UUID |
| name | string | Yes | Human-readable trace name |
| status | string (running, ok, error, partial) | Yes | Trace execution status |
| events | array<object> | Yes | Ordered event summaries for the trace timeline |
| events[].id | string | Yes | Trace event UUID |
| events[].name | string | Yes | Human-readable event name |
| events[].status | string (ok, error, pending) | Yes | Event status |
| events[].started_at | datetime (ISO 8601) | No | Event start time |
| events[].inserted_at | datetime (ISO 8601) | Yes | Record insertion timestamp |
| events[].sequence | integer | Yes | Sequence number within the trace |
| events[].event_type | string | Yes | Event type label |
| events[].duration_ms | integer | No | Duration in milliseconds |
| events[].cost | number | No | Cost attributed to the event |
| events[].ended_at | datetime (ISO 8601) | No | Event end time |
| events[].latency_ms | integer | No | Latency in milliseconds |
| events[].parent_event_id | string | No | Parent event UUID when nested |
| events[].source_event_id | string | No | Caller-supplied source event id when the ingest is idempotent |
| metadata | object | Yes | Read-time redacted metadata payload |
| started_at | datetime (ISO 8601) | Yes | Trace start time |
| request_id | string | No | Internal request identifier |
| inserted_at | datetime (ISO 8601) | Yes | Record insertion timestamp |
| updated_at | datetime (ISO 8601) | Yes | Record update timestamp |
| summary | string | No | Operator-facing summary for the trace |
| environment | string | No | Exact environment label captured at ingest |
| service_agent | object | No | Associated service agent summary |
| service_agent.id | string | Yes | Service agent UUID |
| service_agent.name | string | Yes | Service agent name |
| error_payload | object | Yes | Read-time redacted error payload |
| failure_group | object | No | Failure group linked by matching signature |
| failure_group.id | string | Yes | Failure group UUID |
| failure_group.status | string (open, acknowledged, resolved) | Yes | Failure group status |
| failure_group.title | string | Yes | Failure group title |
| failure_group.severity | string (low, medium, high, critical) | Yes | Failure group severity |
| workflow_target | object | No | Associated workflow target summary |
| workflow_target.id | string | Yes | Workflow target UUID |
| workflow_target.name | string | Yes | Workflow target name |
| duration_ms | integer | No | Trace duration in milliseconds |
| failure_signature | string | No | Failure signature used for grouping |
| input_payload | object | Yes | Read-time redacted input payload |
| output_payload | object | Yes | Read-time redacted output payload |
| redaction_applied | boolean | Yes | True when any operator-visible payload field was masked |
| replayable | boolean | Yes | Whether the trace can be replayed |
| ended_at | datetime (ISO 8601) | No | Trace end time |
| external_trace_id | string | No | External trace identifier from the caller |
| last_activity_at | datetime (ISO 8601) | No | Last observed activity time |
| total_cost | number | No | Accumulated cost across the trace |
| trace_type | string (runtime, eval, replay) | Yes | Trace category |
| workflow_version | object | No | Associated workflow version summary |
| workflow_version.id | string | Yes | Workflow version UUID |
| workflow_version.label | string | Yes | Workflow version label |
Example
{
"duration_ms": 3200,
"ended_at": "2026-03-12T08:45:03Z",
"environment": "production",
"error_payload": {
"email": "[REDACTED]"
},
"events": [
{
"cost": 0.03,
"duration_ms": 950,
"ended_at": "2026-03-12T08:45:02Z",
"event_type": "llm.completion",
"id": "c34b4b67-f304-4b02-a8e1-2a053c4b8381",
"inserted_at": "2026-03-12T08:45:02Z",
"latency_ms": 950,
"name": "draft response",
"parent_event_id": null,
"sequence": 1,
"source_event_id": "evt-checkout-443-1",
"started_at": "2026-03-12T08:45:01Z",
"status": "error"
}
],
"external_trace_id": "trace-checkout-443",
"failure_group": {
"id": "95c77f8c-a4b8-4818-a9bc-aadad23cba02",
"severity": "high",
"status": "open",
"title": "Payment timeout"
},
"failure_signature": "payment:timeout",
"id": "6646e3ff-8f2f-4204-ad5c-f4ebc1830f9e",
"input_payload": {
"authorization": "[REDACTED]"
},
"inserted_at": "2026-03-12T08:45:03Z",
"last_activity_at": "2026-03-12T08:45:03Z",
"metadata": {
"region": "us-east-1"
},
"name": "checkout runtime trace",
"output_payload": {
"result": "retry_exhausted"
},
"redaction_applied": true,
"replayable": true,
"request_id": "req-01HQ5PX7P7F4",
"service_agent": {
"id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
"name": "payments-agent"
},
"started_at": "2026-03-12T08:45:00Z",
"status": "ok",
"summary": "Timeout after payment provider retry budget was exhausted.",
"total_cost": 0.12,
"trace_type": "runtime",
"updated_at": "2026-03-12T08:45:03Z",
"workflow_target": {
"id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
"name": "checkout-api"
},
"workflow_version": {
"id": "d0b91d0c-0f4b-4a28-8d9d-ccf0c427d6e8",
"label": "v2026.03.12"
}
}
401
Invalid or missing token
Invalid or missing token
403
Token lacks traces:read
Token lacks traces:read
404
Trace not found
Trace not found
GET
/api/v1/traces/:trace_id/events
Agent Token
List a trace's events (machine)
traces:read
/api/v1/traces/:trace_id/events
Agent Token
List a trace's events (machine)
Description
Lists events for a trace, ordered by sequence. Requires traces:read. Nested filter[status] (ok | error | pending) and filter[event_type] are applied. Each event includes source_event_id.
Auth
Agent TokenRequired Scopes
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| trace_id | path | string | Yes | Trace UUID |
| filter[status] | query | string | No | Filter by event status |
| filter[event_type] | query | string | No | Exact-match event type filter |
Responses
200
Trace events ordered by sequence
Returns: TraceEventList
Trace events ordered by sequence
Returns: TraceEventList
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| trace_events | array<object> | Yes | List of trace events |
| trace_events[].id | string | Yes | Trace event UUID |
| trace_events[].name | string | Yes | Human-readable event name |
| trace_events[].status | string (ok, error, pending) | Yes | Event status |
| trace_events[].started_at | datetime (ISO 8601) | No | Event start time |
| trace_events[].inserted_at | datetime (ISO 8601) | Yes | Record insertion timestamp |
| trace_events[].sequence | integer | Yes | Sequence number within the trace |
| trace_events[].event_type | string | Yes | Event type label |
| trace_events[].duration_ms | integer | No | Duration in milliseconds |
| trace_events[].cost | number | No | Cost attributed to the event |
| trace_events[].ended_at | datetime (ISO 8601) | No | Event end time |
| trace_events[].latency_ms | integer | No | Latency in milliseconds |
| trace_events[].parent_event_id | string | No | Parent event UUID when nested |
| trace_events[].source_event_id | string | No | Caller-supplied source event id when the ingest is idempotent |
Example
{
"trace_events": [
{
"cost": 0.03,
"duration_ms": 950,
"ended_at": "2026-03-12T08:45:02Z",
"event_type": "llm.completion",
"id": "c34b4b67-f304-4b02-a8e1-2a053c4b8381",
"inserted_at": "2026-03-12T08:45:02Z",
"latency_ms": 950,
"name": "draft response",
"parent_event_id": null,
"sequence": 1,
"source_event_id": "evt-checkout-443-1",
"started_at": "2026-03-12T08:45:01Z",
"status": "error"
}
]
}
401
Invalid or missing token
Invalid or missing token
403
Token lacks traces:read
Token lacks traces:read
GET
/api/v1/traces/:id
Agent Token
Read a trace (machine)
traces:read
/api/v1/traces/:id
Agent Token
Read a trace (machine)
Description
Machine APIAuth with traces:read. This is not a partner route: an mpk_ key never authenticates here (PartnerAuth is not mounted). Partner scopes are workspaces:provision, sso:handoff, webhooks:manage, and engagements:manage; marketplace reconciliation uses the partner engagement APIs, not this route. Returns the trace detail payload (redacted input/output/error/metadata, redaction_applied, events, and optional failure_group), not a TraceSummary.
Auth
Agent TokenRequired Scopes
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Trace UUID |
Responses
200
Trace detail
Returns: Trace
Trace detail
Returns: Trace
Response Body
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Trace UUID |
| name | string | Yes | Human-readable trace name |
| status | string (running, ok, error, partial) | Yes | Trace execution status |
| events | array<object> | Yes | Ordered event summaries for the trace timeline |
| events[].id | string | Yes | Trace event UUID |
| events[].name | string | Yes | Human-readable event name |
| events[].status | string (ok, error, pending) | Yes | Event status |
| events[].started_at | datetime (ISO 8601) | No | Event start time |
| events[].inserted_at | datetime (ISO 8601) | Yes | Record insertion timestamp |
| events[].sequence | integer | Yes | Sequence number within the trace |
| events[].event_type | string | Yes | Event type label |
| events[].duration_ms | integer | No | Duration in milliseconds |
| events[].cost | number | No | Cost attributed to the event |
| events[].ended_at | datetime (ISO 8601) | No | Event end time |
| events[].latency_ms | integer | No | Latency in milliseconds |
| events[].parent_event_id | string | No | Parent event UUID when nested |
| metadata | object | Yes | Read-time redacted metadata payload |
| started_at | datetime (ISO 8601) | Yes | Trace start time |
| request_id | string | No | Internal request identifier |
| inserted_at | datetime (ISO 8601) | Yes | Record insertion timestamp |
| updated_at | datetime (ISO 8601) | Yes | Record update timestamp |
| summary | string | No | Operator-facing summary for the trace |
| environment | string | No | Exact environment label captured at ingest |
| service_agent | object | No | Associated service agent summary |
| service_agent.id | string | Yes | Service agent UUID |
| service_agent.name | string | Yes | Service agent name |
| error_payload | object | Yes | Read-time redacted error payload |
| failure_group | object | No | Failure group linked by matching signature |
| failure_group.id | string | Yes | Failure group UUID |
| failure_group.status | string (open, acknowledged, resolved) | Yes | Failure group status |
| failure_group.title | string | Yes | Failure group title |
| failure_group.severity | string (low, medium, high, critical) | Yes | Failure group severity |
| workflow_target | object | No | Associated workflow target summary |
| workflow_target.id | string | Yes | Workflow target UUID |
| workflow_target.name | string | Yes | Workflow target name |
| duration_ms | integer | No | Trace duration in milliseconds |
| failure_signature | string | No | Failure signature used for grouping |
| input_payload | object | Yes | Read-time redacted input payload |
| output_payload | object | Yes | Read-time redacted output payload |
| redaction_applied | boolean | Yes | True when any operator-visible payload field was masked |
| replayable | boolean | Yes | Whether the trace can be replayed |
| ended_at | datetime (ISO 8601) | No | Trace end time |
| external_trace_id | string | No | External trace identifier from the caller |
| last_activity_at | datetime (ISO 8601) | No | Last observed activity time |
| total_cost | number | No | Accumulated cost across the trace |
| trace_type | string (runtime, eval, replay) | Yes | Trace category |
| workflow_version | object | No | Associated workflow version summary |
| workflow_version.id | string | Yes | Workflow version UUID |
| workflow_version.label | string | Yes | Workflow version label |
Example
{
"duration_ms": 3200,
"ended_at": "2026-03-12T08:45:03Z",
"environment": "production",
"error_payload": {
"email": "[REDACTED]"
},
"events": [
{
"cost": 0.03,
"duration_ms": 950,
"ended_at": "2026-03-12T08:45:02Z",
"event_type": "llm.completion",
"id": "c34b4b67-f304-4b02-a8e1-2a053c4b8381",
"inserted_at": "2026-03-12T08:45:02Z",
"latency_ms": 950,
"name": "draft response",
"parent_event_id": null,
"sequence": 1,
"started_at": "2026-03-12T08:45:01Z",
"status": "error"
}
],
"external_trace_id": "trace-checkout-443",
"failure_group": {
"id": "95c77f8c-a4b8-4818-a9bc-aadad23cba02",
"severity": "high",
"status": "open",
"title": "Payment timeout"
},
"failure_signature": "payment:timeout",
"id": "6646e3ff-8f2f-4204-ad5c-f4ebc1830f9e",
"input_payload": {
"authorization": "[REDACTED]"
},
"inserted_at": "2026-03-12T08:45:03Z",
"last_activity_at": "2026-03-12T08:45:03Z",
"metadata": {
"region": "us-east-1"
},
"name": "checkout runtime trace",
"output_payload": {
"result": "retry_exhausted"
},
"redaction_applied": true,
"replayable": true,
"request_id": "req-01HQ5PX7P7F4",
"service_agent": {
"id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
"name": "payments-agent"
},
"started_at": "2026-03-12T08:45:00Z",
"status": "ok",
"summary": "Timeout after payment provider retry budget was exhausted.",
"total_cost": 0.12,
"trace_type": "runtime",
"updated_at": "2026-03-12T08:45:03Z",
"workflow_target": {
"id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
"name": "checkout-api"
},
"workflow_version": {
"id": "d0b91d0c-0f4b-4a28-8d9d-ccf0c427d6e8",
"label": "v2026.03.12"
}
}
401
Invalid or missing token
Invalid or missing token
403
Token lacks traces:read
Token lacks traces:read
404
Trace not found
Trace not found
GET
/api/v1/traces/:trace_id/events
Agent Token
List a trace's events (machine)
traces:read
/api/v1/traces/:trace_id/events
Agent Token
List a trace's events (machine)
Description
Machine APIAuth with traces:read. Not a partner route: an mpk_ key never authenticates here. Events are ordered by sequence. FilterParams reads the nested filter map only.
Auth
Agent TokenRequired Scopes
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| trace_id | path | string | Yes | Trace UUID |
| filter[status] | query | string | No | Filter by event status |
| filter[event_type] | query | string | No | Filter by event_type |
Responses
200
Trace events ordered by sequence. Each row includes source_event_id.
Trace events ordered by sequence. Each row includes source_event_id.
401
Invalid or missing token
Invalid or missing token
403
Token lacks traces:read
Token lacks traces:read