Skip to main content

​
Overview

The Improve Run Events endpoint streams live progress updates for a Cloud Improve run using Server-Sent Events (SSE). Use it to track a run from enqueue through completion without polling. The stream is resumable — pass a Last-Event-ID header or cursor query parameter to replay events you may have missed after a disconnect.

​
Stream events

GET /api/v1/improve-runs/{id}/events
Authorization: Bearer {API_KEY}
Last-Event-ID: {last_event_id}   (optional — resume from a prior position)
ParameterLocationRequiredDescription
idPathYesThe improve run UUID
Last-Event-IDHeaderNoResume the stream after this event ID
cursorQueryNoAlias for Last-Event-ID when headers are not available
The endpoint returns Content-Type: text/event-stream. Each SSE message carries a JSON payload in its data field.

​
Example stream

id: evt_01hwz...
event: run_enqueued
data: {"id":"evt_01hwz...","run_id":"run_abc...","org_id":"org_xyz...","type":"run_enqueued","status":"queued","created_at":"2026-04-17T10:00:00Z"}

id: evt_01hwz2...
event: run_started
data: {"id":"evt_01hwz2...","run_id":"run_abc...","org_id":"org_xyz...","type":"run_started","status":"running","created_at":"2026-04-17T10:00:05Z"}

id: evt_01hwz3...
event: phase_changed
data: {"id":"evt_01hwz3...","run_id":"run_abc...","org_id":"org_xyz...","type":"phase_changed","phase":"generating","created_at":"2026-04-17T10:00:10Z"}

id: evt_01hwz4...
event: candidate_persisted
data: {"id":"evt_01hwz4...","run_id":"run_abc...","org_id":"org_xyz...","type":"candidate_persisted","candidate_id":"cand_...","created_at":"2026-04-17T10:00:30Z"}

id: evt_01hwz5...
event: run_completed
data: {"id":"evt_01hwz5...","run_id":"run_abc...","org_id":"org_xyz...","type":"run_completed","status":"succeeded","created_at":"2026-04-17T10:01:00Z"}

​
Event types

TypeMeaning
run_enqueuedRun has been accepted and placed in the execution queue
run_startedRun is now actively executing on the runtime
phase_changedThe run has moved to a new execution phase (see phase field)
candidate_persistedA candidate skill revision has been saved (see candidate_id)
proposal_createdAn evolution proposal has been created from a candidate (see proposal_id)
run_completedRun finished with a terminal success outcome (succeeded or no_winner)
run_failedRun encountered a fatal error
run_cancelledRun was cancelled before completion

​
Event object

Every event in the stream has the following shape:
FieldTypeDescription
idstringUnique event ID — use as Last-Event-ID to resume
run_idstringThe improve run this event belongs to
org_idstringYour organisation ID
typestringOne of the event types above
statusstring | undefinedRun status at the time of the event
phasestring | undefinedPresent on phase_changed events
candidate_idstring | undefinedPresent on candidate_persisted events
proposal_idstring | undefinedPresent on proposal_created events
payloadobject | undefinedAdditional event-specific data
created_atstringISO 8601 timestamp

​
Resuming after a disconnect

Store the id field from the last event you successfully processed. On reconnect, pass it as either:
  • Last-Event-ID request header (preferred)
  • cursor query parameter (useful when headers cannot be customised)
The stream replays any events that occurred after that position, so you will not miss transitions that happened while you were disconnected.

​
JavaScript example

const runId = "run_abc123";
const apiKey = process.env.SELFTUNE_API_KEY;

const response = await fetch(
  `https://api.selftune.dev/api/v1/improve-runs/${runId}/events`,
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "text/event-stream",
    },
  }
);

// Parse the SSE stream with your preferred client or stream parser.

​
Error responses

StatusMeaning
401Missing or invalid API key
403Run does not belong to your organisation
404Run ID not found
503Cloud Improve runtime is not configured for your account