Skip to main content
GET
/
api
/
v1
/
tasks
/
{id}
/
stream
Stream Events
curl --request GET \
  --url https://api.example.com/api/v1/tasks/{id}/stream

Documentation Index

Fetch the complete documentation index at: https://docs.sigmic.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Stream Task Events

Connect to the unified SSE stream to receive the complete conversation history followed by live execution events. This is the recommended way to build a real-time chat UI.

​
Request

GET /api/v1/tasks/{id}/stream
Authorization: Bearer {api_key}

​
Path Parameters

ParameterTypeDescription
idstringThe unique task identifier

​
Stream Behavior

The stream delivers events in three phases:
  1. History replay - Emits history_message events for each saved conversation message
  2. History complete - Emits history_done with { messageCount, isStreaming }
  3. Live events (if task is running) - Catch-up state followed by real-time content, thought, tool_call, tool_result, subagent_start, subagent_thought, subagent_tool, subagent_end, error, and done events
If the task is not currently running, the stream ends after history_done.

​
Reconnection

You can disconnect and reconnect at any time. On reconnect, the stream replays the full history and catches up to the current state. The task continues executing in the background regardless of stream connections - disconnecting does not cancel the task.

​
Heartbeat

The server sends :heartbeat comments every 15 seconds to keep the connection alive. These can be safely ignored by your SSE parser.

​
Stream Output Example

event: history_message
data: {"id":"msg-1","role":"user","content":"Analyze this CSV file","createdAt":"2026-01-26T15:50:54.870Z","attachedFiles":[{"name":"data.csv","path":"uploads/data.csv"}]}

event: history_message
data: {"id":"msg-2","role":"assistant","content":"I analyzed the CSV file...","createdAt":"2026-01-26T15:50:59.998Z","thoughts":[{"subject":"Analyzing","description":"Reading CSV structure"}],"toolCalls":[{"callId":"tc-1","toolName":"read_file","status":"success"}]}

event: history_done
data: {"messageCount":2,"isStreaming":true}

event: content
data: {"text":"Now let me provide additional analysis...","isPartial":true}

event: tool_call
data: {"callId":"call_456","toolName":"write_file","status":"executing","args":{"path":"output.csv"}}

event: tool_result
data: {"callId":"call_456","status":"success","output":"File written successfully"}

event: subagent_start
data: {"agentName":"code-writer","displayName":"Code Writer","description":"Writes and edits code files","objective":"Create summary chart"}

event: subagent_thought
data: {"agentName":"code-writer","text":"I'll generate a chart from the analyzed data"}

event: subagent_tool
data: {"agentName":"code-writer","status":"end","toolName":"write_file","output":"Chart saved"}

event: subagent_end
data: {"agentName":"code-writer","terminateReason":"GOAL","result":"Created summary chart"}

event: content
data: {"text":"I've created the output file.","isPartial":false}

event: done
data: {"finalResponse":"I've created the output file with the analysis results."}

​
Event Types

​
history_message

A replayed conversation message from history. 
{
  "id": "msg-1",
  "role": "user",
  "content": "Analyze this CSV file",
  "createdAt": "2026-01-26T15:50:54.870Z",
  "attachedFiles": [
    { "name": "data.csv", "path": "uploads/data.csv" }
  ]
}
FieldTypeDescription
idstringMessage identifier
rolestringuser or assistant
contentstringMessage text
createdAtstringISO timestamp
attachedFilesarrayUploaded files (user messages only)
thoughtsarrayAgent reasoning (assistant messages only)
toolCallsarrayTool executions (assistant messages only)

​
history_done

Signals that history replay is complete. 
{
  "messageCount": 2,
  "isStreaming": true
}
FieldTypeDescription
messageCountnumberNumber of history messages sent
isStreamingbooleanWhether the task is currently running (live events follow if true)

​
Live Events

After history_done, if isStreaming is true, the stream delivers live events including content, thought, tool_call, tool_result, subagent events (subagent_start, subagent_thought, subagent_tool, subagent_end), error, and done. See Streaming Events for the complete event format reference.

​
Examples

# Stream events (Ctrl+C to disconnect - task keeps running)
curl -N https://api.sigmic.ai/api/v1/tasks/YOUR_TASK_ID/stream \
  -H "Authorization: Bearer sigmic_your_key_here"

​
Use Cases

​
Building a Chat UI

Use the stream endpoint to hydrate your chat interface and receive live updates: 
async function connectToTask(taskId) {
  const messages = [];

  const response = await fetch(`${API_BASE}/api/v1/tasks/${taskId}/stream`, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  // Parse SSE events...
  // history_message events → populate chat history
  // history_done → render the chat UI
  // content events → update current assistant message in real-time
  // done event → finalize the message
}

​
Reconnecting After Disconnect

// User switches tabs, connection drops
// When they come back, just reconnect:
async function reconnect(taskId) {
  // Same endpoint - replays full history + catches up
  return connectToTask(taskId);
}
The stream endpoint is the recommended way to consume task events. It replaces the previous pattern of reading SSE from POST endpoints. Use GET /tasks/:id/history as a REST alternative when SSE is not practical.

​
Errors

CodeDescription
AUTH_REQUIREDNo authentication provided
INVALID_API_KEYInvalid or expired API key
NOT_FOUNDTask with the specified ID was not found