User guideAI Engineering Platform
Back to siteSite

API · SSE event catalog

GET /api/v1/orgs/{org}/runs/{run}/events

Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no

Protocol

id: 41
event: phase.completed
data: {"run_id":"7c9e","phase":"implement","duration_ms":142300,"ts":"2026-10-21T18:22:09Z"}

: ping
  • id = run_events.seq (increases monotonically per run). On reconnect the client sends Last-Event-ID; the server first backfills from the database, then subscribes to Redis.
  • An unknown event type is ignored (forward compatibility).
  • Heartbeat : ping every 15s. The server closes the connection after 1h; the client reconnects.
  • retry: 3000 is sent at the start of the stream.
  • If Last-Event-ID does not exist in the database (archived), the server sends event: stream.reset with {"from_seq": N} and continues from the oldest available.

Types

eventWhendata (key fields)
run.queuedrun createdrun_id, agent_type, model
run.startedworker picked it upstarted_at
phase.startedentering a phasephase, attempt
phase.completedleaving a phasephase, duration_ms, meta
phase.failedphase failedphase, code, detail
llm.startedbefore the LLM callmodel, prompt_tokens_est
llm.chunktoken streamtext (delta), index
llm.completedend of the calltokens_in, tokens_out, cost_micros, finish_reason
tool.calltool calltool, args_digest, permitted
tool.resultresulttool, ok, duration_ms, bytes
file.changedFS change in the sandboxpath, change (added/modified/deleted)
plan.readyplan ready for approvalartifact_id, sha256, summary
approval.requestedwaiting for a humanapproval_id, type
approval.decideddecisionapproval_id, status, decided_by
test.started / test.completedtest runsuite, passed, failed, coverage_pct
diff.readydiff finalizedartifact_id, files, additions, deletions
usage.updatedafter every LLM calltokens_in, tokens_out, cost_micros, budget_pct
run.succeededendduration_ms, head_commit, pr_url?
run.failedendcode, detail, retryable
run.canceledcancellationrequested_by
stream.resetgap in the historyfrom_seq

Ordering and guarantees

  • Events of the same run are ordered by seq; the client must not assume they arrive exactly once — a duplicate is skipped by id.
  • llm.chunk is best-effort (it may be lost on reconnect); the full text is in the log artifact. After a reconnect the UI loads the last N events and continues.
  • No llm.chunk carries prompt/system messages (only the model output).

Minimal client pseudocode

const es = new EventSource(url, { withCredentials: false });
es.onmessage = (m) => apply(JSON.parse(m.data));
es.addEventListener('run.failed', (m) => showError(JSON.parse(m.data)));
es.onerror = () => { /* EventSource reconnects by itself; on 401 → refresh token */ };

SSE authorization goes through the Authorization header, so in practice fetch + ReadableStream is used (EventSource does not send headers). Reference implementation: web/src/lib/sse.ts.