API reference

Live events (SSE)

The run screen stays live through one server-sent event stream per run. You can subscribe to the same stream from a script.

Stream run events#

GET/api/runs/{run_id}/eventsbearer token or ?token=

Opens a text/event-stream. The first event is always a snapshot. After that the stream sends sim, log and kernel events as they happen, and a : keepalive comment after 15 seconds without one. The stream does not close when the run finishes.

Path parameters#

name	type	description
`run_id`	`str`	The run's `id`, such as `run-9f56e171af08`.

Query parameters#

name	type	description
`token` optional	`str`	Your `CASCADE_TOKEN`. Use it when you can't set headers, as with `EventSource`. If present, it is checked instead of the header.

Returns#

200 with a text/event-stream of RunEvent, one JSON object per data: line.

Errors#

status	when
`401`	The `Authorization` header is missing, is not `Bearer <token>`, or the token is wrong.
`404`	No run has this id.

Example#

bash

curl -N -H "Authorization: Bearer $CASCADE_TOKEN" \
  "$CASCADE_URL/api/runs/run-210d75c008c4/events"

python

import json
import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
url = f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4/events"
with httpx.stream("GET", url, headers=headers, timeout=None) as resp:
    for line in resp.iter_lines():
        if line.startswith("data: "):
            event = json.loads(line[6:])
            print(event["type"])

// EventSource cannot send headers, so pass the token as a query parameter.
const url = `${CASCADE_URL}/api/runs/run-210d75c008c4/events?token=${encodeURIComponent(CASCADE_TOKEN)}`;
const events = new EventSource(url);
events.onmessage = (msg) => {
  const event = JSON.parse(msg.data);
  console.log(event.type);
};

Wire format#

Each event is one data: line holding one JSON object, followed by a blank line. The stream uses no event: or id: fields, so read the object's type to tell events apart.

text

data: {"type":"snapshot","run":{"id":"run-9f56e171af08","trace_id":"demo", ...}, "kernels":[]}

data: {"type":"sim","sim":{"id":"sim-70f1ae5fc7c6","state":"running", ...}}

: keepalive

The response sets Cache-Control: no-cache and X-Accel-Buffering: no, so proxies pass events through as they happen.

Events#

These events come from the captured run. Each shows the first event of its kind that the stream sent.

snapshot#

Always first. It holds the whole RunDetail as it is at connect time and every finished KernelStat so far, with each stats map emptied to keep the event small. Full stats come in live kernel events and in the results downloads. In this capture the stream connected right after the run was created, so both sims are still launching and no kernel has finished.

data: snapshot event

{
  "type": "snapshot",
  "run": {
    "id": "run-210d75c008c4",
    "trace_id": "demo",
    "created_at": "2026-11-08T08:59:03.024065Z",
    "state": "active",
    "entries": [
      {
        "gpu_config": "SM86_RTX3070",
        "count": 2
      }
    ],
    "sim_counts": {
      "launching": 2
    },
    "sample": false,
    "trace": {
      "id": "demo",
      "state": "ready",
      "error": null,
      "created_at": "2026-11-08T08:59:02.587743Z",
      "updated_at": "2026-11-08T08:59:02.592073Z",
      "model": null,
      "layers": [],
      "source_gpu": null,
      "trace_gpu_arch": "sm_86",
      "suggested_sim_config": "SM86_RTX3070",
      "kernel_count": 20,
      "bytes": 16890250,
      "has_real_timing": false,
      "has_step_timeline": true,
      "sample": false
    },
    "sims": [
      {
        "id": "sim-1047ddbdf5b1",
        "run_id": "run-210d75c008c4",
        "gpu_config": "SM86_RTX3070",
        "replica": 0,
        "state": "launching",
        "error": null,
        "launcher_ref": "64418",
        "created_at": "2026-11-08T08:59:03.024065Z",
        "started_at": null,
        "finished_at": null,
        "last_heartbeat_at": null,
        "exit_code": null,
        "kernels_done": 0,
        "kernels_total": 20,
        "current_kernel": null,
        "latest": {
          "gpu_tot_sim_cycle": null,
          "gpu_tot_sim_insn": null,
          "gpu_tot_ipc": null,
          "sim_rate_ips": null
        },
        "log_tail": []
      },
      {
        "id": "sim-e8f63b6b3bed",
        "run_id": "run-210d75c008c4",
        "gpu_config": "SM86_RTX3070",
        "replica": 1,
        "state": "launching",
        "error": null,
        "launcher_ref": "64419",
        "created_at": "2026-11-08T08:59:03.024065Z",
        "started_at": null,
        "finished_at": null,
        "last_heartbeat_at": null,
        "exit_code": null,
        "kernels_done": 0,
        "kernels_total": 20,
        "current_kernel": null,
        "latest": {
          "gpu_tot_sim_cycle": null,
          "gpu_tot_sim_insn": null,
          "gpu_tot_ipc": null,
          "sim_rate_ips": null
        },
        "log_tail": []
      }
    ]
  },
  "kernels": []
}

sim#

A sim changed: its state, its heartbeat time, its progress or its latest metrics. It carries the whole SimSummary, so replace your copy of that sim.

data: sim event

{
  "type": "sim",
  "sim": {
    "id": "sim-e8f63b6b3bed",
    "run_id": "run-210d75c008c4",
    "gpu_config": "SM86_RTX3070",
    "replica": 1,
    "state": "running",
    "error": null,
    "launcher_ref": "64419",
    "created_at": "2026-11-08T08:59:03.024065Z",
    "started_at": "2026-11-08T08:59:03.224173Z",
    "finished_at": null,
    "last_heartbeat_at": "2026-11-08T08:59:03.224173Z",
    "exit_code": null,
    "kernels_done": 0,
    "kernels_total": 20,
    "current_kernel": null,
    "latest": {
      "gpu_tot_sim_cycle": null,
      "gpu_tot_sim_insn": null,
      "gpu_tot_ipc": null,
      "sim_rate_ips": null
    },
    "log_tail": []
  }
}

The same event when a sim finishes.

data: sim event, sim finished

{
  "type": "sim",
  "sim": {
    "id": "sim-1047ddbdf5b1",
    "run_id": "run-210d75c008c4",
    "gpu_config": "SM86_RTX3070",
    "replica": 0,
    "state": "succeeded",
    "error": null,
    "launcher_ref": "64418",
    "created_at": "2026-11-08T08:59:03.024065Z",
    "started_at": "2026-11-08T08:59:03.224424Z",
    "finished_at": "2026-11-08T08:59:06.130355Z",
    "last_heartbeat_at": "2026-11-08T08:59:06.130355Z",
    "exit_code": 0,
    "kernels_done": 6,
    "kernels_total": 20,
    "current_kernel": "_Z10dot_kernelIdEvPKT_S2_PS0_i",
    "latest": {
      "gpu_tot_sim_cycle": 76713.0,
      "gpu_tot_sim_insn": 26560256.0,
      "gpu_tot_ipc": 346.2289,
      "sim_rate_ips": 510774.0
    },
    "log_tail": [
      "Reply_Network_in_buffer_full_per_cycle =       0.0000",
      "Reply_Network_in_buffer_avg_util =       0.0000",
      "Reply_Network_out_buffer_full_per_cycle =       0.0000"
      /* 17 more items trimmed */
    ]
  }
}

log#

New output from one sim, exactly as the simulator sent it in one chunk.

data: log event

{
  "type": "log",
  "sim_id": "sim-e8f63b6b3bed",
  "lines": [
    "GPGPU-Sim version 4.2.0 (build gpgpu-sim_git-commit-13c67115070dc2f0876254a790d0238073ca364a-modified_590.0) configured with AccelWattch.",
    "",
    "----------------------------------------------------------------------------"
    /* 197 more items trimmed */
  ]
}

kernel#

A kernel finished on one sim. The stat carries the full stats map.

data: kernel event

{
  "type": "kernel",
  "stat": {
    "sim_id": "sim-1047ddbdf5b1",
    "kernel_index": 0,
    "kernel_name": "_Z11init_kernelIdEvPT_S1_S1_S0_S0_S0_",
    "kernel_launch_uid": 1,
    "gpu_sim_cycle": 6174,
    "gpu_sim_insn": 19456,
    "gpu_ipc": 3.1513,
    "sim_time_ns": 5454.063604240282,
    "stats": {
      "kernel_name": "_Z11init_kernelIdEvPT_S1_S1_S0_S0_S0_",
      "kernel_launch_uid": 1.0,
      "gpu_sim_cycle": 6174.0,
      "gpu_sim_insn": 19456.0,
      "gpu_ipc": 3.1513,
      "gpu_tot_sim_cycle": 6174.0
      /* 943 more keys trimmed */
    }
  }
}

Order and reconnects#

Events arrive in the order the app committed them, and the snapshot never overlaps an event that follows it. Apply the snapshot, then apply each event on top.
For one log chunk the order is log, then any kernel events it completed, then sim.
The app keeps up to 2000 unsent events per subscriber. A subscriber that falls further behind is disconnected. Reconnect and start again from the new snapshot. EventSource reconnects by itself.
The stream stays open after the run finishes. Close it when the run's state is no longer active.