Real-Time Events (SSE)

The Events endpoint provides a real-time stream of simulation activity using Server-Sent Events (SSE). This is the primary mechanism for building live dashboards and monitoring tools.

Subscribe to Events

GET /v1/simulations/{id}/events

Opens a persistent SSE connection that streams simulation events in real time.

Scope required: simulation:read

Path Parameters

Parameter	Type	Description
id	uuid	Simulation ID

Connection Details

• Content-Type: text/event-stream
• Connection: Keep-alive
• Heartbeat: Every 30 seconds (to prevent proxy timeouts)
• Concurrency: Limited by your license tier (see Rate Limiting)

Event Types

Event	Description
tick	A simulation step was computed
loss	A basin loss (irreversible collapse) occurred
warning	A stability warning threshold was crossed
paradox	A paradox was detected
decree	A decree was submitted and applied
prophecy	A new prophecy was generated
simulation:status	The simulation’s status changed (e.g., paused, completed)
error	A simulation error occurred
heartbeat	Keep-alive signal (no payload)

Event Format

Each event follows the standard SSE format:

event: tick
data: {"t":42,"b":0,"lastMove":"idle","state":{...},"warning":null,"agents":[...]}

event: loss
data: {"tick":247,"magnitude":0.6133,"agent":"frontier_model"}

event: heartbeat
data:

Example — curl

curl -N https://api.anankelabs.ai/v1/simulations/a1b2c3d4-.../events \
  -H "X-Api-Key: krs_..."

Example — JavaScript

const eventSource = new EventSource(
  "https://api.anankelabs.ai/v1/simulations/a1b2c3d4-.../events",
  {
    headers: { "X-Api-Key": "krs_..." }
  }
);

eventSource.addEventListener("tick", (e) => {
  const step = JSON.parse(e.data);
  console.log(`Tick ${step.t}, stability: ${step.state.stability}`);
});

eventSource.addEventListener("loss", (e) => {
  const loss = JSON.parse(e.data);
  console.log(`Basin loss at tick ${loss.tick}!`);
});

eventSource.addEventListener("error", (e) => {
  console.error("SSE error:", e);
  eventSource.close();
});

Example — Python

import json
import httpx

url = "https://api.anankelabs.ai/v1/simulations/a1b2c3d4-.../events"
headers = {"X-Api-Key": "krs_..."}

with httpx.stream("GET", url, headers=headers) as response:
    for line in response.iter_lines():
        if line.startswith("data:"):
            payload = line.removeprefix("data:").strip()
            if payload:
                event = json.loads(payload)
                print(event)

Notes

• The SSE connection counts against your tier’s concurrent SSE limit, not the per-minute rate limit.
• If you exceed the concurrent SSE limit, the server returns 429 Too Many Requests.
• Clients should handle reconnection gracefully — the EventSource API does this automatically in browsers.