`GET /simulations/{simulationKey}/runs/{runIndex}/stream`

Stream a simulation run's data as server-sent events or newline-delimited JSON.

Path Parameters

`simulationKey`

The unique key identifying the simulation.

`runIndex`

The index of the simulation run (starting from 1).

Query Parameters

`limit` (optional)

Maximum number of events to return. Must be between 1 and 1,000,000. Defaults to 1,000,000.

`lastEventId` (optional)

Resume streaming from after this event ID. Used for reconnection. Must be within the simulation run's reconnect window.

Request Headers

`Accept`

Specify the desired response format:

text/event-stream - Server-sent events format (default)
application/x-ndjson - Newline-delimited JSON format

Success

Responds with a 200 OK and the following headers:

Content-Type: text/event-stream or application/x-ndjson
Transfer-Encoding: chunked
Connection: keep-alive

Server-Sent Events Format

Each event has a type specified by the event field and includes:

event - Event type (e.g., create or error)
data - JSON-encoded event data
id - Event ID for reconnection

The data field contains:

entity - The entity name (for create events)
offset - Milliseconds elapsed in the simulation when the event occurred
value - The event payload (JSON value)

NDJSON Format

Each line contains a JSON object with:

type - create or error
id - Event ID
entity - Entity name (for create events)
offset - Milliseconds elapsed
value - Event payload

Other Responses

204 No Content - Stream has been exhausted (all events have been consumed)

400 Bad Request - Invalid query parameters (e.g., lastEventId is outside the reconnect window)

404 Not Found - Simulation run not found

406 Not Acceptable - Unsupported Accept header

Examples

Server-Sent Events

Data from a simulation with a "users" entity:

event: create
id: 1
data: {"entity":"users","offset":683878,"value":{"id": 1, "name": "Alice Jones"}}

event: create
id: 2
data: {"entity":"users","offset":729698,"value":{"id": 2, "name": "Bob Hyland"}}

Using curl

Stream simulation data to a JSON lines file:

curl -N \
  'https://api.rngo.dev/simulations/my-sim/runs/1/stream' \
  -H 'Authorization: Bearer rngo_...' \
  -H 'Accept: application/x-ndjson' \
  | jq -r '.value' \
  > users.jsonl

Resume streaming from a specific event:

curl -N \
  'https://api.rngo.dev/simulations/my-sim/runs/1/stream?lastEventId=100' \
  -H 'Authorization: Bearer rngo_...' \
  -H 'Accept: text/event-stream'

GET /simulations/{simulationKey}/runs/{runIndex}/stream