Server-Sent Events (SSE)

Cortex provides SSE endpoints for streaming execution progress. Unlike WebSocket (which broadcasts to all subscribers), SSE streams are per-request and one-directional — ideal for monitoring a specific agent execution or workflow in progress.

Agent Execution Stream

GET /api/streaming/agents/:name/stream

Streams real-time progress of an agent's current execution.

Request

curl -N https://api.cortex.acrobi.com/api/streaming/agents/my-agent/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Reconnection

Include Last-Event-ID header to resume from where you left off:

curl -N https://api.cortex.acrobi.com/api/streaming/agents/my-agent/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Last-Event-ID: 42"

Event Format

id: 1
event: progress
data: {"step": "analyzing", "message": "Reading codebase...", "progress": 0.2}

id: 2
event: progress
data: {"step": "implementing", "message": "Writing code...", "progress": 0.5}

id: 3
event: complete
data: {"result": "Task completed successfully", "duration": 12500}

Workflow Execution Stream

GET /api/streaming/workflows/:id/stream

Streams progress across all steps of a multi-step workflow.

Request

curl -N https://api.cortex.acrobi.com/api/streaming/workflows/wf-123/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Event Format

id: 1
event: step_start
data: {"stepId": "step-1", "name": "Code Review", "agent": "reviewer-agent"}

id: 2
event: step_progress
data: {"stepId": "step-1", "progress": 0.75, "message": "Found 3 issues"}

id: 3
event: step_complete
data: {"stepId": "step-1", "result": "3 issues found", "duration": 8000}

id: 4
event: step_start
data: {"stepId": "step-2", "name": "Fix Issues", "agent": "coder-agent"}

Keepalive

The server sends a heartbeat comment every 15 seconds to prevent proxy timeouts:

: heartbeat

When to Use SSE vs WebSocket

Use Case	Recommended
Monitor a single execution in progress	SSE
Dashboard receiving updates from many agents	WebSocket
Long-running workflow progress bar	SSE
Real-time activity feed	WebSocket
Webhook event debugging	WebSocket

JavaScript Client

const eventSource = new EventSource(
  `https://api.cortex.acrobi.com/api/streaming/agents/my-agent/stream`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);

eventSource.addEventListener('progress', (e) => {
  const data = JSON.parse(e.data);
  updateProgressBar(data.progress);
});

eventSource.addEventListener('complete', (e) => {
  const data = JSON.parse(e.data);
  showResult(data.result);
  eventSource.close();
});

eventSource.onerror = () => {
  // Auto-reconnects with Last-Event-ID
};