Streaming

Real-time updates via Server-Sent Events (SSE).

Send X-API-Version: 2 on the initial request (same as other REST endpoints). SSE event payloads are not wrapped in the version 1 envelope. See REST overview — API version.

Stream Task Updates

GET /tasks/:id/stream

Stream task status updates in real-time.

Headers

1Accept: text/event-stream

Event Format

1event: update2data: {"id":"task_abc","status":7,"logs":"Processing..."}34event: update5data: {"id":"task_abc","status":10,"output":{...}}67event: done8data: {}

Event Types

cURL Example

1curl -N https://api.inference.sh/tasks/task_abc123/stream \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Accept: text/event-stream"

Stream workspace events

GET /events

Real-time updates for resources in your workspace. The inference.sh app uses this stream to refresh user profile, billing transactions, and engine state without polling.

Requires authentication with teams:read scope.

Format negotiation

Send X-API-Version: 2 on the initial request.

NDJSON messages

Each line is a JSON object. Heartbeats use {"type":"heartbeat"} (every 10 seconds).

Typed updates include an event field set to the resource table name:

1{"event":"engines","data":{"id":"eng_abc","status":"running",...}}2{"event":"transactions","data":{"id":"txn_xyz","amount":500,...}}3{"event":"users","data":{"id":"usr_123","balance":10000,...}}

Subscribe to the event names you care about (engines, transactions, users). Partial field updates may include a fields array alongside data.

SSE format

1event: engines2data: {"id":"eng_abc","status":"running",...}34: heartbeat

The event name matches the resource type (same table names as NDJSON).

cURL example

1curl -N https://api.inference.sh/events \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Accept: application/x-ndjson"

When to use this vs other streams

There is no last_event_id resume on /events — open a new connection after disconnects.

Stream engine updates

GET /engines/{id}/stream

Stream status changes for a single private engine. Requires engines:read scope.

Send Accept: text/event-stream and X-API-Version: 2. Events use the same SSE pattern as task streaming: update events with engine DTO payloads, done when the stream closes, and heartbeat comments every 10 seconds.

1curl -N https://api.inference.sh/engines/eng_abc123/stream \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Accept: text/event-stream"

In the JavaScript SDK: client.engines.stream(engineId).

Stream Chat Messages

GET /chats/:id/messages/stream

Stream agent response in real-time. Create a chat and send the first message with the Agents API before opening this stream.

When the stream ends with event: done, fetch structured results (if any) with GET /chats/:id — see Get Chat.

Event Format

1event: content2data: {"text":"Hello"}34event: content5data: {"text":", how"}67event: tool_call8data: {"id":"tc_123","name":"search","arguments":{...}}910event: done11data: {}

Event Types

Connection Parameters

Handling Reconnection

SSE supports automatic reconnection. Use the Last-Event-ID header:

1curl -N https://api.inference.sh/tasks/task_abc123/stream \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-API-Version: 2" \4  -H "Accept: text/event-stream" \5  -H "Last-Event-ID: evt_xyz"

JavaScript Example

1const eventSource = new EventSource(2  'https://api.inference.sh/tasks/task_abc123/stream',3  {4    headers: {5      'Authorization': 'Bearer inf_your_key'6    }7  }8);910eventSource.addEventListener('update', (event) => {11  const data = JSON.parse(event.data);12  console.log('Status:', data.status);13});1415eventSource.addEventListener('done', () => {16  eventSource.close();17});