Events reference

Run events are the primary way to observe run progress. Both SSE (GET /v1/runs/{id}/events/stream) and cursor-based polling (GET /v1/runs/{id}/events) return events in the same wire shape. For how to consume streams, handle cursors, and interpret run status, see Run lifecycle.

Event envelope

Each event is a PublicRunEvent object:

Field	Type	Description
`seq`	integer	Monotonically increasing sequence number per run
`type`	string	Event type identifier (see sections below)
`timestamp`	string	ISO 8601 timestamp
`payload`	object	`{ redacted: boolean, value: object }` — see below

The internal database row may include a UUID id and runId; these are not included in the public API response.

Payload redaction

When an event’s stored payload is a plain object, RunEventService may strip client-supplied fields before returning it:

Removed keys: input, metadata, attachment_refs, sensitivity_tags
When any of those keys were present, payload.redacted is true
All other keys are copied into payload.value

Assistant-generated content (for example content, content_delta on step events) is not removed by this pass.

Lifecycle events

`run.created`

Emitted when a run is accepted and enqueued (RunLifecycleService.createRun).

Payload field	Type	Notes
`request_id`	string	Correlation ID
`input`	object	Client input (omitted when redacted)
`metadata`	object	Client metadata (omitted when redacted)
`attachment_refs`	array	References (omitted when redacted)
`sensitivity_tags`	array	Sensitivity tags (omitted when redacted)
`streaming`	boolean	Optional, when supplied at create
`routing_hint`	string	Optional
`routing`	object	Optional routing metadata

Example (redacted public view — sensitive keys stripped):

{
  "seq": 1,
  "type": "run.created",
  "timestamp": "2026-03-25T14:30:00.000Z",
  "payload": {
    "redacted": true,
    "value": {
      "request_id": "uuid",
      "routing": { "routing_decision_reason": "planner_first_step" }
    }
  }
}

Status transition shape (worker and some lifecycle events)

These events include a transition payload with request_id, from_status, to_status, and usually reason_code: run.worker.started — Worker claimed the run; status moves to running. run.worker.succeeded — Run completed successfully (terminal). run.worker.failed — Run failed (terminal). run.worker.stalled — Run marked stalled (e.g. lease loss). run.worker.retry_scheduled — Run returned to queued for retry.

Payload field	Type	Notes
`request_id`	string	Correlation ID
`from_status`	string	Previous run status
`to_status`	string	New run status
`reason_code`	string \| null	Machine reason when applicable; `null` for `run.worker.started`

Example (run.worker.started):

{
  "seq": 2,
  "type": "run.worker.started",
  "timestamp": "2026-03-25T14:30:01.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "request_id": "uuid",
      "from_status": "queued",
      "to_status": "running",
      "reason_code": null
    }
  }
}

`run.cancelled` and `run.resumed`

run.cancelled — Run moved to cancelled (terminal). run.resumed — Run resumed from stalled or similar; to_status is running or queued. Payload includes request_id, from_status, and to_status only (no reason_code on these events in the current implementation). Example (run.cancelled):

{
  "seq": 42,
  "type": "run.cancelled",
  "timestamp": "2026-03-25T15:00:00.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "request_id": "uuid",
      "from_status": "running",
      "to_status": "cancelled"
    }
  }
}

`run.limit_exceeded`

Emitted when a run hits a configured hard limit (RunLimitEnforcer).

Payload field	Type	Notes
`limitType`	string	Which limit was exceeded
`currentValue`	number	Observed value
`threshold`	number	Configured threshold
`unit`	string	Unit for the limit

Example:

{
  "seq": 50,
  "type": "run.limit_exceeded",
  "timestamp": "2026-03-25T16:00:00.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "limitType": "duration_ms",
      "currentValue": 3600000,
      "threshold": 3600000,
      "unit": "ms"
    }
  }
}

Step events

`step.progress`

Streaming progress during a step (AgentLoopDriver): content deltas or tool-call milestones.

Payload field	Type	Notes
`task_id`	string	Optional task identifier
`kind`	string	`content_delta`, `tool_call_start`, or `tool_call_done`
`content_delta`	string	Present when `kind` is `content_delta`
`tool_call_id`	string	Optional; tool-related kinds
`tool_name`	string	Optional; tool-related kinds
`request_id`	string	Optional correlation ID

Example (content_delta):

{
  "seq": 10,
  "type": "step.progress",
  "timestamp": "2026-03-25T14:30:05.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "task_id": "task_abc",
      "kind": "content_delta",
      "content_delta": "Here is the answer: ",
      "request_id": "uuid"
    }
  }
}

`step.done`

Step finished with full assistant text and execution outcome (StepDonePayload).

Payload field	Type	Notes
`task_id`	string	Optional task identifier
`content`	string	Full assistant response text for this step
`outcome`	string	`succeeded`, `retry_step`, or `fail_run` (see below)
`reason_code`	string	Optional; often set when `outcome` is `fail_run`
`provider_error_message`	string	Optional; provider error detail when `outcome` is `fail_run`
`request_id`	string	Optional correlation ID

outcome values (StepExecutionOutcome):

succeeded — Step completed successfully; orchestration continues per plan.
retry_step — Orchestrator will retry the step (not a run-level failure by itself).
fail_run — Run should transition to failed (terminal failure path).

Example:

{
  "seq": 15,
  "type": "step.done",
  "timestamp": "2026-03-25T14:30:10.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "task_id": "task_abc",
      "content": "Final assistant message for the step.",
      "outcome": "succeeded",
      "request_id": "uuid"
    }
  }
}

Tool events

`run.tool.invoked`

Emitted when a tool invocation completes (RunToolInvokedPayload).

Payload field	Type	Notes
`tool_call_id`	string	Unique invocation ID
`tool_name`	string	Catalog tool name
`tool_outcome`	string	Typically `succeeded`, `failed`, `timeout`, or `policy_denied`
`tool_input_summary`	object	`ToolSummaryEnvelope` (bounded input summary)
`tool_output_summary`	object	`ToolSummaryEnvelope` (bounded output summary)
`policy_reason_code`	string \| null	Set when denied by policy
`duration_ms`	number	Wall-clock duration

Tool summary envelope (`tool_input_summary` / `tool_output_summary`)

Field	Type	Notes
`schema_version`	string	Always `"v1"`
`preview`	string	Optional; up to first 240 characters
`highlights`	array	Optional; up to 10 items: `{ key, value, redacted }` each
`stats`	object	`fields_total`, `fields_redacted`, `bytes_before_redaction`, `bytes_after_redaction`
`truncated`	boolean	Whether summary was truncated

Example:

{
  "seq": 12,
  "type": "run.tool.invoked",
  "timestamp": "2026-03-25T14:30:08.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "tool_call_id": "call_001",
      "tool_name": "memory_search",
      "tool_outcome": "succeeded",
      "tool_input_summary": {
        "schema_version": "v1",
        "preview": "{\"query\":\"docs\"}",
        "highlights": [
          { "key": "query", "value": "docs", "redacted": false }
        ],
        "stats": {
          "fields_total": 1,
          "fields_redacted": 0,
          "bytes_before_redaction": 20,
          "bytes_after_redaction": 20
        },
        "truncated": false
      },
      "tool_output_summary": {
        "schema_version": "v1",
        "stats": {
          "fields_total": 0,
          "fields_redacted": 0,
          "bytes_before_redaction": 0,
          "bytes_after_redaction": 0
        },
        "truncated": false
      },
      "policy_reason_code": null,
      "duration_ms": 45
    }
  }
}

Coordination events

`run.coordination.decision`

Planner/worker/judge coordination outcome (RunOrchestratorService).

Payload field	Type	Notes
`request_id`	string	Correlation ID
`decision_type`	string	e.g. `continue`, `replan`, `stop`, `await_input`
`reason_code`	string	Machine-readable reason
`role`	string	e.g. `planner`, `worker`, `judge`
`judge_decision`	object	Optional; e.g. `{ decision, reason }` from judge evaluation

Example:

{
  "seq": 20,
  "type": "run.coordination.decision",
  "timestamp": "2026-03-25T14:35:00.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "request_id": "uuid",
      "decision_type": "continue",
      "reason_code": "JUDGE_CONTINUE",
      "role": "judge"
    }
  }
}

`run.awaiting_input`

Run is paused for human or client input.

Payload field	Type	Notes
`request_id`	string	Correlation ID
`reason_code`	string	Why input is needed
`input_kind`	string	Optional: e.g. `approval`, `rejection`, `payload`

Example:

{
  "seq": 21,
  "type": "run.awaiting_input",
  "timestamp": "2026-03-25T14:35:01.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "request_id": "uuid",
      "reason_code": "AWAITING_APPROVAL",
      "input_kind": "approval"
    }
  }
}

`run.signal_applied`

A signal was applied (RunSignalService).

Payload field	Type	Notes
`request_id`	string	Correlation ID
`action`	string	`approve` or `reject`

Example:

{
  "seq": 22,
  "type": "run.signal_applied",
  "timestamp": "2026-03-25T14:36:00.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "request_id": "uuid",
      "action": "approve"
    }
  }
}

`run.input_received`

Client submitted input via signal (action: submit_input).

Payload field	Type	Notes
`request_id`	string	Correlation ID
`action`	string	`submit_input`

Example:

{
  "seq": 23,
  "type": "run.input_received",
  "timestamp": "2026-03-25T14:36:05.000Z",
  "payload": {
    "redacted": false,
    "value": {
      "request_id": "uuid",
      "action": "submit_input"
    }
  }
}

Event type quick reference

Type	Category	Run terminal?	Description
`run.created`	Lifecycle	No	Run accepted and enqueued
`run.worker.started`	Lifecycle	No	Worker started execution
`run.worker.succeeded`	Lifecycle	Yes	Run completed successfully
`run.worker.failed`	Lifecycle	Yes	Run failed
`run.worker.stalled`	Lifecycle	No	Run marked stalled
`run.worker.retry_scheduled`	Lifecycle	No	Run queued for retry
`run.cancelled`	Lifecycle	Yes	Run cancelled
`run.resumed`	Lifecycle	No	Run resumed from paused/stalled
`run.limit_exceeded`	Lifecycle	Yes	Hard limit hit
`step.progress`	Step	No	Streaming progress / tool milestones
`step.done`	Step	No	Step completed with full content
`run.tool.invoked`	Tool	No	Tool invocation finished
`run.coordination.decision`	Coordination	No	Planner/worker/judge decision
`run.awaiting_input`	Coordination	No	Waiting for signal/input
`run.signal_applied`	Coordination	No	Approve/reject applied
`run.input_received`	Coordination	No	Input payload submitted

API examples

List events (replace run_xxx with your run id):

curl -sS "https://api.example.com/v1/runs/run_xxx/events?limit=50" \
  -H "Authorization: Bearer key_abc123xyz:your_secret_here"

Open an SSE stream:

curl -sSN "https://api.example.com/v1/runs/run_xxx/events/stream" \
  -H "Authorization: Bearer key_abc123xyz:your_secret_here" \
  -H "Accept: text/event-stream"

Guides

​Events reference

​Event envelope

​Payload redaction

​Lifecycle events

​run.created

​Status transition shape (worker and some lifecycle events)

​run.cancelled and run.resumed

​run.limit_exceeded

​Step events

​step.progress

​step.done

​Tool events

​run.tool.invoked

​Tool summary envelope (tool_input_summary / tool_output_summary)

​Coordination events

​run.coordination.decision

​run.awaiting_input

​run.signal_applied

​run.input_received

​Event type quick reference

​API examples

Events reference

Event envelope

Payload redaction

Lifecycle events

`run.created`

Status transition shape (worker and some lifecycle events)

`run.cancelled` and `run.resumed`

`run.limit_exceeded`

Step events

`step.progress`

`step.done`

Tool events

`run.tool.invoked`

Tool summary envelope (`tool_input_summary` / `tool_output_summary`)

Coordination events

`run.coordination.decision`

`run.awaiting_input`

`run.signal_applied`

`run.input_received`

Event type quick reference

API examples