API reference

Runs

A run simulates one ready trace on a list of GPU configs. These routes create and cancel runs, read their sims, and download what the sims produced. Runs covers the same ground as a guide.

List GPU configs#

GET/api/gpu-configsbearer token

Lists the GPU configs the app found at startup under $CASCADE_ACCELSIM_DIR/gpu-simulator/gpgpu-sim/configs/tested-cfgs/*/gpgpusim.config. The app derives arch from the directory name (SM90_H100 is sm_90, SM7_QV100 is sm_70) and reads core_clock_mhz from the first value of -gpgpu_clock_domains. A directory whose name or clock it can't read is skipped.

Returns#

200 with a list of GpuConfig, sorted by name.

Errors#

status	when
`401`	The `Authorization` header is missing, is not `Bearer <token>`, or the token is wrong.

Example#

bash

curl "$CASCADE_URL/api/gpu-configs" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/gpu-configs", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/gpu-configs`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

[
  {
    "name": "SM7_QV100",
    "arch": "sm_70",
    "core_clock_mhz": 1132.0
  },
  {
    "name": "SM80_A100",
    "arch": "sm_80",
    "core_clock_mhz": 1410.0
  },
  {
    "name": "SM86_RTX3070",
    "arch": "sm_86",
    "core_clock_mhz": 1132.0
  },
  {
    "name": "SM90_H100",
    "arch": "sm_90",
    "core_clock_mhz": 1980.0
  },
  {
    "name": "SM90_H200",
    "arch": "sm_90",
    "core_clock_mhz": 1980.0
  }
]

Create a run#

POST/api/runsbearer token

Creates a run and starts launching its sims in the background. Each entry fans out to count sims, numbered by replica from 0. The response comes back before any sim has launched, so every sim is pending or launching. Follow progress with Stream run events or by polling Get a run.

Request body#

JSON, RunCreate.

field	type	description
`trace_id`	`str`	A trace in state `ready`.
`entries`	`list[RunEntry]`	One entry per config. Each fans out to `count` sims. at least 1 item

Each RunEntry has these fields.

field	type	description
`gpu_config`	`str`	A `GpuConfig.name` whose `arch` matches the trace's `trace_gpu_arch`.
`count`	`int`	How many sims run this config. at least 1, at most 64

Returns#

201 with a RunDetail.

Errors#

status	when
`401`	The `Authorization` header is missing, is not `Bearer <token>`, or the token is wrong.
`404`	`trace_id` names no trace.
`409`	The trace is not `ready`, or is a sample, which has no instruction traces.
`422`	An entry names an unknown `gpu_config`, or a config whose `arch` differs from the trace's `trace_gpu_arch`.
`422`	The body fails validation: `entries` is empty, or a `count` is outside 1 to 64.

Example#

bash

curl -X POST "$CASCADE_URL/api/runs" \
  -H "Authorization: Bearer $CASCADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trace_id": "demo", "entries": [{"gpu_config": "SM86_RTX3070", "count": 2}]}'

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.post(f"{os.environ['CASCADE_URL']}/api/runs", headers=headers, json={"trace_id": "demo", "entries": [{"gpu_config": "SM86_RTX3070", "count": 2}]})
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs`, {
  method: "POST",
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({"trace_id": "demo", "entries": [{"gpu_config": "SM86_RTX3070", "count": 2}]}),
});
console.log(await resp.json());

Response · 201 Created · application/json

{
  "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": {
    "pending": 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": "pending",
      "error": null,
      "launcher_ref": null,
      "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": "pending",
      "error": null,
      "launcher_ref": null,
      "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": []
    }
  ]
}

409 response · 409 Conflict · application/json

{
  "detail": "trace demo-failed is failed, not ready"
}

422 response, arch mismatch · 422 Unprocessable Entity · application/json

{
  "detail": "SM90_H100 is sm_90 but trace demo is sm_86"
}

422 response, validation · 422 Unprocessable Entity · application/json

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": [
        "body",
        "entries",
        0,
        "count"
      ],
      "msg": "Input should be greater than or equal to 1",
      "input": 0,
      "ctx": {
        "ge": 1
      }
    }
  ]
}

List runs#

GET/api/runsbearer token

Lists every run, newest first, with per-state sim counts. Use Get a run for the sims themselves.

Returns#

200 with a list of RunSummary.

Errors#

status	when
`401`	The `Authorization` header is missing, is not `Bearer <token>`, or the token is wrong.

Example#

bash

curl "$CASCADE_URL/api/runs" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

[
  {
    "id": "run-210d75c008c4",
    "trace_id": "demo",
    "created_at": "2026-11-08T08:59:03.024065Z",
    "state": "succeeded",
    "entries": [
      {
        "gpu_config": "SM86_RTX3070",
        "count": 2
      }
    ],
    "sim_counts": {
      "succeeded": 2
    },
    "sample": false
  },
  {
    "id": "run-sample-opt125m-h100-e2e",
    "trace_id": "sample__facebook_opt-125m__h100-e2e",
    "created_at": "2026-11-08T06:50:10Z",
    "state": "succeeded",
    "entries": [
      {
        "gpu_config": "SM90_H100",
        "count": 1
      }
    ],
    "sim_counts": {
      "succeeded": 1
    },
    "sample": true
  }
]

Get a run#

GET/api/runs/{run_id}bearer token

Returns the run, its trace, and every sim with its state, progress, latest metrics and last 20 log lines.

Path parameters#

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

Returns#

200 with a RunDetail.

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 "$CASCADE_URL/api/runs/run-210d75c008c4" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs/run-210d75c008c4`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

{
  "id": "run-210d75c008c4",
  "trace_id": "demo",
  "created_at": "2026-11-08T08:59:03.024065Z",
  "state": "succeeded",
  "entries": [
    {
      "gpu_config": "SM86_RTX3070",
      "count": 2
    }
  ],
  "sim_counts": {
    "succeeded": 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": "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 */
      ]
    },
    {
      "id": "sim-e8f63b6b3bed",
      "run_id": "run-210d75c008c4",
      "gpu_config": "SM86_RTX3070",
      "replica": 1,
      "state": "succeeded",
      "error": null,
      "launcher_ref": "64419",
      "created_at": "2026-11-08T08:59:03.024065Z",
      "started_at": "2026-11-08T08:59:03.224173Z",
      "finished_at": "2026-11-08T08:59:06.164567Z",
      "last_heartbeat_at": "2026-11-08T08:59:06.164567Z",
      "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 */
      ]
    }
  ]
}

404 response · 404 Not Found · application/json

{
  "detail": "run run-000000000000 not found"
}

Cancel a run#

POST/api/runs/{run_id}/cancelbearer token

Moves every sim that has not finished to cancelled and asks the launcher to stop it. Sims that already finished keep their state. The next heartbeat from a cancelled sim gets cancel: true. Calling it again changes nothing, so it is safe to retry. On a sample run it changes nothing either, since its sim already succeeded.

Path parameters#

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

Returns#

200 with the RunDetail after cancelling.

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 -X POST "$CASCADE_URL/api/runs/run-b42541e17665/cancel" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.post(f"{os.environ['CASCADE_URL']}/api/runs/run-b42541e17665/cancel", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs/run-b42541e17665/cancel`, {
  method: "POST",
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

{
  "id": "run-b42541e17665",
  "trace_id": "demo",
  "created_at": "2026-11-08T08:59:06.669870Z",
  "state": "cancelled",
  "entries": [
    {
      "gpu_config": "SM86_RTX3070",
      "count": 1
    }
  ],
  "sim_counts": {
    "cancelled": 1
  },
  "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-57c51b464fc9",
      "run_id": "run-b42541e17665",
      "gpu_config": "SM86_RTX3070",
      "replica": 0,
      "state": "cancelled",
      "error": null,
      "launcher_ref": "64556",
      "created_at": "2026-11-08T08:59:06.669870Z",
      "started_at": null,
      "finished_at": "2026-11-08T08:59:06.673285Z",
      "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": []
    }
  ]
}

Compare real and simulated time#

GET/api/runs/{run_id}/comparisonbearer token

Lines up kernels by order. Row i holds the ith kernel the sims finished and the ith row of the trace's real timing, sorted by kernel_id. For each config, sim_ns is the median sim_time_ns over that config's replicas, or null if no replica has finished that kernel. real_ns is null until the trace has real timing, which the profiler does not capture yet.

Path parameters#

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

Returns#

200 with a Comparison.

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 "$CASCADE_URL/api/runs/run-210d75c008c4/comparison" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4/comparison", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs/run-210d75c008c4/comparison`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

{
  "has_real_timing": false,
  "configs": [
    "SM86_RTX3070"
  ],
  "rows": [
    {
      "kernel_index": 0,
      "kernel_name": "_Z11init_kernelIdEvPT_S1_S1_S0_S0_S0_",
      "real_ns": null,
      "sim_ns": {
        "SM86_RTX3070": 5454.063604240282
      }
    },
    {
      "kernel_index": 1,
      "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
      "real_ns": null,
      "sim_ns": {
        "SM86_RTX3070": 5232.332155477032
      }
    },
    {
      "kernel_index": 2,
      "kernel_name": "_Z10mul_kernelIdEvPT_PKS0_",
      "real_ns": null,
      "sim_ns": {
        "SM86_RTX3070": 5491.166077738516
      }
    }
    /* 3 more items trimmed */
  ]
}

List a run's kernel timings#

GET/api/runs/{run_id}/kernelsbearer token

Returns a KernelStat for every kernel every sim in the run has finished, ordered by config, replica, then kernel. Each stats map is empty to keep the response small; the full maps are in the results downloads. Laying each sim's kernels end to end by sim_time_ns gives its timeline, which is what the app's timeline and Compare views draw.

Path parameters#

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

Returns#

200 with a list of KernelStat.

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 "$CASCADE_URL/api/runs/run-210d75c008c4/kernels" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4/kernels", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs/run-210d75c008c4/kernels`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

[
  {
    "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": {}
  },
  {
    "sim_id": "sim-1047ddbdf5b1",
    "kernel_index": 1,
    "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
    "kernel_launch_uid": 2,
    "gpu_sim_cycle": 5923,
    "gpu_sim_insn": 11264,
    "gpu_ipc": 1.9017,
    "sim_time_ns": 5232.332155477032,
    "stats": {}
  },
  {
    "sim_id": "sim-1047ddbdf5b1",
    "kernel_index": 2,
    "kernel_name": "_Z10mul_kernelIdEvPT_PKS0_",
    "kernel_launch_uid": 3,
    "gpu_sim_cycle": 6216,
    "gpu_sim_insn": 12288,
    "gpu_ipc": 1.9768,
    "sim_time_ns": 5491.166077738516,
    "stats": {}
  }
  /* 9 more items trimmed */
]

List a run's step timing#

GET/api/runs/{run_id}/step-timelinesbearer token

Returns a SimStepTimeline for every sim in the run that has sent step timing, ordered by config, then replica. A sim sends one after it succeeds on a trace whose has_step_timeline is true, so the list is empty until then, and stays empty for other traces. simulated is a full simulated_timeline.json, with every kernel of every step, so for a real model it can be several megabytes per sim. Per-kind step means are in simulated.summary.per_kind, coverage is in simulated.summary.simulation.coverage, and per-step and per-request errors against the real run are in compare.

Path parameters#

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

Returns#

200 with a list of SimStepTimeline.

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 "$CASCADE_URL/api/runs/run-210d75c008c4/step-timelines" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4/step-timelines", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs/run-210d75c008c4/step-timelines`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

[
  {
    "sim_id": "sim-1047ddbdf5b1",
    "gpu_config": "SM86_RTX3070",
    "replica": 0,
    "simulated": {
      "meta": {
        "run_name": "offline-h100-derived-fixture",
        "model": "facebook/opt-125m",
        "prompt": "Hello, my name is",
        "max_tokens": 4,
        "repeats": 1,
        "exec_mode": "eager",
        "gpu_name": "NVIDIA H100 80GB HBM3",
        "sm_clock_mhz_median": 1980,
        "mem_clock_mhz": 3106,
        "vllm_version": "fixture-unknown",
        "layerwise_nvtx": false,
        "fixture_provenance": "Actual nsys kernel names/dimensions/durations and simulator cycles; synthetic phase assignment, baseline/profiled walls, queue/API values and rescaled gaps. Not a real corrected_timeline capture. Synthetic consistent absolute step/request timestamps and baseline inter-step gaps added for gap-aware replay."
      },
      "steps": [
        {
          "step": -1,
          "repeat": -1,
          "warmup": true,
          "kind": "prefill",
          "num_reqs": 1,
          "num_scheduled_tokens": 6,
          "baseline_wall_ns": 9000000,
          "profiled_wall_ns": null,
          "gpu_busy_ns": null,
          "cuda_api_ns": null,
          "host_ns": null,
          "kernels": [],
          "baseline_wall_start_ns": 100000000,
          "baseline_wall_end_ns": 109000000,
          "baseline_gap_before_ns": null,
          "profiled_wall_start_ns": null,
          "profiled_wall_end_ns": null,
          "profiled_gap_before_ns": null
        },
        {
          "step": 0,
          "repeat": 0,
          "warmup": false,
          "kind": "prefill",
          "num_reqs": 1,
          "num_scheduled_tokens": 6,
          "baseline_wall_ns": 6507260.692579505,
          "profiled_wall_ns": 6507260.692579505,
          "gpu_busy_ns": 544095.6925795053,
          "cuda_api_ns": null,
          "host_ns": 5963165,
          "kernels": [
            {
              "seq": 536,
              "name": "_ZN8cublasLt19splitKreduce_kernelILi32ELi16Eif6__halffS1_Lb0EfS1_S1_Lb1ELb1ELb0ELb0EEEvNS_18cublasSplitKParamsIT4_EEPKT2_PKT8_PT7_PT3_PKS3_SG_PKT9_S7_PSH_PvlPS3_PiSM_SM_SG_SG_SG_SG_SG_",
              "grid": "24x1x1",
              "block": "32x16x1",
              "duration_ns": 2016,
              "start_offset_ns": 108088.07402640952
            },
            {
              "seq": 537,
              "name": "_ZN2at6native29vectorized_elementwise_kernelILi8ENS0_15CUDAFunctor_addIN3c104HalfEEESt5arrayIPcLm3EEEEviT0_T1_",
              "grid": "5x1x1",
              "block": "128x1x1",
              "duration_ns": 1376,
              "start_offset_ns": 150410.8374180178
            }
            /* 150 more items trimmed */
          ],
          "baseline_wall_start_ns": 1000200000,
          "baseline_wall_end_ns": 1006707260.6925795,
          "baseline_gap_before_ns": null,
          "profiled_wall_start_ns": 1000200000,
          "profiled_wall_end_ns": 1006707260.6925795,
          "profiled_gap_before_ns": null
        }
        /* 3 more items trimmed */
      ],
      "requests": [
        {
          "repeat": -1,
          "warmup": true,
          "queued_ms": 0,
          "ttft_ms": 9,
          "itl_ms_mean": null,
          "itl_ms_p50": null,
          "e2e_ms": 9,
          "num_output_tokens": 1
        },
        {
          "repeat": 0,
          "warmup": false,
          "queued_ms": 0.2,
          "ttft_ms": 6.707260692579508,
          "itl_ms_mean": 5.79187032508834,
          "itl_ms_p50": 5.65,
          "e2e_ms": 24.082871667844532,
          "num_output_tokens": 4,
          "arrival_ns": 1000000000,
          "pre_first_step_ns": 200000,
          "post_last_step_ns": 0,
          "first_step_start_ns": 1000200000,
          "last_step_end_ns": 1024082871.6678445,
          "first_token_ns": 1006707260.6925795,
          "last_token_ns": 1024082871.6678445
        }
      ],
      "summary": {
        "simulation": {
          "host_model": "scaled-gaps",
          "host_fit": {},
          "coverage": {
            "kernels": 683,
            "simulated_kernels": 6,
            "kernel_fraction": 0.008784773060029283,
            "gpu_time_fraction": 0.011172026136868988,
            "measured_gpu_ns": 2228423.0,
            "covered_measured_gpu_ns": 24896.0,
            "unmodeled_gpu_ns": 0.0,
            "steps": [
              {
                "repeat": 0,
                "step": 0,
                "kernels": 152,
                "simulated_kernels": 5,
                "measured_gpu_ns": 536835,
                "simulated_coverage_gpu_ns": 20128.0,
                "unmodeled_gpu_ns": 0,
                "measured_kernel_overlap_ns": 0.0
              },
              {
                "repeat": 0,
                "step": 1,
                "kernels": 177,
                "simulated_kernels": 1,
                "measured_gpu_ns": 564801,
                "simulated_coverage_gpu_ns": 4768.0,
                "unmodeled_gpu_ns": 0,
                "measured_kernel_overlap_ns": 0.0
              }
              /* 2 more items trimmed */
            ]
          },
          "request_assumption": "one request per repeat; queued (or arrival) + pre/steps/inter-step gaps/post",
          "gap_model": "measured",
          "gap_fit": {}
        },
        "per_kind": {
          "prefill": {
            "steps": 1,
            "wall_ns_mean": 6507260.692579505,
            "gpu_busy_ns_mean": 544095.6925795053
          },
          "decode": {
            "steps": 3,
            "wall_ns_mean": 4791870.325088339,
            "gpu_busy_ns_mean": 575732.9917550059,
            "gap_before_ns": {
              "n": 3,
              "mean": 1000000,
              "p50": 1000000,
              "p95": 1180000.0
            }
          }
        }
      }
    },
    "compare": {
      "steps": [
        {
          "repeat": 0,
          "step": 0,
          "kind": "prefill",
          "wall_ns": {
            "real": 6500000,
            "simulated": 6507260.692579505,
            "error": 7260.692579505034,
            "error_pct": 0.1117029627616159
          },
          "gpu_busy_ns": {
            "real": 536835,
            "simulated": 544095.6925795053,
            "error": 7260.692579505267,
            "error_pct": 1.3524998518176472
          }
        },
        {
          "repeat": 0,
          "step": 1,
          "kind": "decode",
          "wall_ns": {
            "real": 4790000,
            "simulated": 4825610.975265018,
            "error": 35610.97526501771,
            "error_pct": 0.7434441600212466
          },
          "gpu_busy_ns": {
            "real": 564801,
            "simulated": 600411.9752650177,
            "error": 35610.97526501771,
            "error_pct": 6.3050481966246
          }
        }
        /* 2 more items trimmed */
      ],
      "requests": [
        {
          "repeat": 0,
          "ttft_ms": {
            "real": 6.7,
            "simulated": 6.707260692579508,
            "error": 0.00726069257950801,
            "error_pct": 0.10836854596280611
          },
          "itl_ms_mean": {
            "real": 5.78,
            "simulated": 5.79187032508834,
            "error": 0.011870325088339406,
            "error_pct": 0.20536894616504162
          },
          "itl_ms_p50": {
            "real": 5.65,
            "simulated": 5.65,
            "error": 0.0,
            "error_pct": 0.0
          },
          "e2e_ms": {
            "real": 24.04,
            "simulated": 24.082871667844532,
            "error": 0.042871667844533334,
            "error_pct": 0.1783347248108708
          }
        }
      ],
      "summary": {
        "wall_ns": {
          "count": 4,
          "mean_error": 10717.916961130686,
          "mean_abs_error": 10717.916961130686,
          "p50_abs_error": 3630.346289752517,
          "p95_abs_error": 31358.4328621908,
          "mean_error_pct": 0.2137867806957156,
          "mean_abs_error_pct": 0.2137867806957156,
          "p50_abs_error_pct": 0.05585148138080795,
          "p95_abs_error_pct": 0.6486829804323018
        },
        "gpu_busy_ns": {
          "count": 4,
          "mean_error": 10717.916961130744,
          "mean_abs_error": 10717.916961130744,
          "p50_abs_error": 3630.3462897526333,
          "p95_abs_error": 31358.432862190835,
          "mean_error_pct": 1.914387012110562,
          "mean_abs_error_pct": 1.914387012110562,
          "p50_abs_error_pct": 0.6762499259088236,
          "p95_abs_error_pct": 5.562165944903556
        }
      }
    }
  },
  {
    "sim_id": "sim-e8f63b6b3bed",
    "gpu_config": "SM86_RTX3070",
    "replica": 1,
    "simulated": {
      "meta": {
        "run_name": "offline-h100-derived-fixture",
        "model": "facebook/opt-125m",
        "prompt": "Hello, my name is",
        "max_tokens": 4,
        "repeats": 1,
        "exec_mode": "eager",
        "gpu_name": "NVIDIA H100 80GB HBM3",
        "sm_clock_mhz_median": 1980,
        "mem_clock_mhz": 3106,
        "vllm_version": "fixture-unknown",
        "layerwise_nvtx": false,
        "fixture_provenance": "Actual nsys kernel names/dimensions/durations and simulator cycles; synthetic phase assignment, baseline/profiled walls, queue/API values and rescaled gaps. Not a real corrected_timeline capture. Synthetic consistent absolute step/request timestamps and baseline inter-step gaps added for gap-aware replay."
      },
      "steps": [
        {
          "step": -1,
          "repeat": -1,
          "warmup": true,
          "kind": "prefill",
          "num_reqs": 1,
          "num_scheduled_tokens": 6,
          "baseline_wall_ns": 9000000,
          "profiled_wall_ns": null,
          "gpu_busy_ns": null,
          "cuda_api_ns": null,
          "host_ns": null,
          "kernels": [],
          "baseline_wall_start_ns": 100000000,
          "baseline_wall_end_ns": 109000000,
          "baseline_gap_before_ns": null,
          "profiled_wall_start_ns": null,
          "profiled_wall_end_ns": null,
          "profiled_gap_before_ns": null
        },
        {
          "step": 0,
          "repeat": 0,
          "warmup": false,
          "kind": "prefill",
          "num_reqs": 1,
          "num_scheduled_tokens": 6,
          "baseline_wall_ns": 6507260.692579505,
          "profiled_wall_ns": 6507260.692579505,
          "gpu_busy_ns": 544095.6925795053,
          "cuda_api_ns": null,
          "host_ns": 5963165,
          "kernels": [
            {
              "seq": 536,
              "name": "_ZN8cublasLt19splitKreduce_kernelILi32ELi16Eif6__halffS1_Lb0EfS1_S1_Lb1ELb1ELb0ELb0EEEvNS_18cublasSplitKParamsIT4_EEPKT2_PKT8_PT7_PT3_PKS3_SG_PKT9_S7_PSH_PvlPS3_PiSM_SM_SG_SG_SG_SG_SG_",
              "grid": "24x1x1",
              "block": "32x16x1",
              "duration_ns": 2016,
              "start_offset_ns": 108088.07402640952
            },
            {
              "seq": 537,
              "name": "_ZN2at6native29vectorized_elementwise_kernelILi8ENS0_15CUDAFunctor_addIN3c104HalfEEESt5arrayIPcLm3EEEEviT0_T1_",
              "grid": "5x1x1",
              "block": "128x1x1",
              "duration_ns": 1376,
              "start_offset_ns": 150410.8374180178
            }
            /* 150 more items trimmed */
          ],
          "baseline_wall_start_ns": 1000200000,
          "baseline_wall_end_ns": 1006707260.6925795,
          "baseline_gap_before_ns": null,
          "profiled_wall_start_ns": 1000200000,
          "profiled_wall_end_ns": 1006707260.6925795,
          "profiled_gap_before_ns": null
        }
        /* 3 more items trimmed */
      ],
      "requests": [
        {
          "repeat": -1,
          "warmup": true,
          "queued_ms": 0,
          "ttft_ms": 9,
          "itl_ms_mean": null,
          "itl_ms_p50": null,
          "e2e_ms": 9,
          "num_output_tokens": 1
        },
        {
          "repeat": 0,
          "warmup": false,
          "queued_ms": 0.2,
          "ttft_ms": 6.707260692579508,
          "itl_ms_mean": 5.79187032508834,
          "itl_ms_p50": 5.65,
          "e2e_ms": 24.082871667844532,
          "num_output_tokens": 4,
          "arrival_ns": 1000000000,
          "pre_first_step_ns": 200000,
          "post_last_step_ns": 0,
          "first_step_start_ns": 1000200000,
          "last_step_end_ns": 1024082871.6678445,
          "first_token_ns": 1006707260.6925795,
          "last_token_ns": 1024082871.6678445
        }
      ],
      "summary": {
        "simulation": {
          "host_model": "scaled-gaps",
          "host_fit": {},
          "coverage": {
            "kernels": 683,
            "simulated_kernels": 6,
            "kernel_fraction": 0.008784773060029283,
            "gpu_time_fraction": 0.011172026136868988,
            "measured_gpu_ns": 2228423.0,
            "covered_measured_gpu_ns": 24896.0,
            "unmodeled_gpu_ns": 0.0,
            "steps": [
              {
                "repeat": 0,
                "step": 0,
                "kernels": 152,
                "simulated_kernels": 5,
                "measured_gpu_ns": 536835,
                "simulated_coverage_gpu_ns": 20128.0,
                "unmodeled_gpu_ns": 0,
                "measured_kernel_overlap_ns": 0.0
              },
              {
                "repeat": 0,
                "step": 1,
                "kernels": 177,
                "simulated_kernels": 1,
                "measured_gpu_ns": 564801,
                "simulated_coverage_gpu_ns": 4768.0,
                "unmodeled_gpu_ns": 0,
                "measured_kernel_overlap_ns": 0.0
              }
              /* 2 more items trimmed */
            ]
          },
          "request_assumption": "one request per repeat; queued (or arrival) + pre/steps/inter-step gaps/post",
          "gap_model": "measured",
          "gap_fit": {}
        },
        "per_kind": {
          "prefill": {
            "steps": 1,
            "wall_ns_mean": 6507260.692579505,
            "gpu_busy_ns_mean": 544095.6925795053
          },
          "decode": {
            "steps": 3,
            "wall_ns_mean": 4791870.325088339,
            "gpu_busy_ns_mean": 575732.9917550059,
            "gap_before_ns": {
              "n": 3,
              "mean": 1000000,
              "p50": 1000000,
              "p95": 1180000.0
            }
          }
        }
      }
    },
    "compare": {
      "steps": [
        {
          "repeat": 0,
          "step": 0,
          "kind": "prefill",
          "wall_ns": {
            "real": 6500000,
            "simulated": 6507260.692579505,
            "error": 7260.692579505034,
            "error_pct": 0.1117029627616159
          },
          "gpu_busy_ns": {
            "real": 536835,
            "simulated": 544095.6925795053,
            "error": 7260.692579505267,
            "error_pct": 1.3524998518176472
          }
        },
        {
          "repeat": 0,
          "step": 1,
          "kind": "decode",
          "wall_ns": {
            "real": 4790000,
            "simulated": 4825610.975265018,
            "error": 35610.97526501771,
            "error_pct": 0.7434441600212466
          },
          "gpu_busy_ns": {
            "real": 564801,
            "simulated": 600411.9752650177,
            "error": 35610.97526501771,
            "error_pct": 6.3050481966246
          }
        }
        /* 2 more items trimmed */
      ],
      "requests": [
        {
          "repeat": 0,
          "ttft_ms": {
            "real": 6.7,
            "simulated": 6.707260692579508,
            "error": 0.00726069257950801,
            "error_pct": 0.10836854596280611
          },
          "itl_ms_mean": {
            "real": 5.78,
            "simulated": 5.79187032508834,
            "error": 0.011870325088339406,
            "error_pct": 0.20536894616504162
          },
          "itl_ms_p50": {
            "real": 5.65,
            "simulated": 5.65,
            "error": 0.0,
            "error_pct": 0.0
          },
          "e2e_ms": {
            "real": 24.04,
            "simulated": 24.082871667844532,
            "error": 0.042871667844533334,
            "error_pct": 0.1783347248108708
          }
        }
      ],
      "summary": {
        "wall_ns": {
          "count": 4,
          "mean_error": 10717.916961130686,
          "mean_abs_error": 10717.916961130686,
          "p50_abs_error": 3630.346289752517,
          "p95_abs_error": 31358.4328621908,
          "mean_error_pct": 0.2137867806957156,
          "mean_abs_error_pct": 0.2137867806957156,
          "p50_abs_error_pct": 0.05585148138080795,
          "p95_abs_error_pct": 0.6486829804323018
        },
        "gpu_busy_ns": {
          "count": 4,
          "mean_error": 10717.916961130744,
          "mean_abs_error": 10717.916961130744,
          "p50_abs_error": 3630.3462897526333,
          "p95_abs_error": 31358.432862190835,
          "mean_error_pct": 1.914387012110562,
          "mean_abs_error_pct": 1.914387012110562,
          "p50_abs_error_pct": 0.6762499259088236,
          "p95_abs_error_pct": 5.562165944903556
        }
      }
    }
  }
]

Download run results#

GET/api/runs/{run_id}/resultsbearer token

Returns everything about a run as one JSON download, with Content-Disposition: attachment; filename="<run_id>-results.json". Each sim's kernels carry the full stats map, every key = value line Accel-Sim printed for that kernel, which is about 30 KB per kernel.

Path parameters#

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

Returns#

200 with a RunResults.

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 -OJ "$CASCADE_URL/api/runs/run-210d75c008c4/results" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4/results", headers=headers)
resp.raise_for_status()
open("run-210d75c008c4-results.json", "wb").write(resp.content)

const resp = await fetch(`${CASCADE_URL}/api/runs/run-210d75c008c4/results`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
const data = await resp.json();

Response · 200 OK · application/json

{
  "run": {
    "id": "run-210d75c008c4",
    "trace_id": "demo",
    "created_at": "2026-11-08T08:59:03.024065Z",
    "state": "succeeded",
    "entries": [
      {
        "gpu_config": "SM86_RTX3070",
        "count": 2
      }
    ],
    "sim_counts": {
      "succeeded": 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,
    "metadata": {
      "status": "ok",
      "files": [
        {
          "key": "accelsim-traces/demo/configs/config_hopper_islip.icnt",
          "bytes": 1352
        },
        {
          "key": "accelsim-traces/demo/configs/gpgpusim.config",
          "bytes": 6028
        }
        /* 25 more items trimmed */
      ],
      "trace_gpu_arch": "sm_86",
      "suggested_sim_config": "SM86_RTX3070"
    },
    "kernels": []
  },
  "sims": [
    {
      "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 */
        ]
      },
      "trace_id": "demo",
      "gpu_config": {
        "name": "SM86_RTX3070",
        "arch": "sm_86",
        "core_clock_mhz": 1132.0
      },
      "kernels": [
        {
          "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
            /* 945 more keys trimmed */
          }
        },
        {
          "sim_id": "sim-1047ddbdf5b1",
          "kernel_index": 1,
          "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
          "kernel_launch_uid": 2,
          "gpu_sim_cycle": 5923,
          "gpu_sim_insn": 11264,
          "gpu_ipc": 1.9017,
          "sim_time_ns": 5232.332155477032,
          "stats": {
            "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
            "kernel_launch_uid": 2.0,
            "gpu_sim_cycle": 5923.0,
            "gpu_sim_insn": 11264.0
            /* 950 more keys trimmed */
          }
        }
        /* 4 more items trimmed */
      ],
      "totals": {
        "gpu_tot_sim_cycle": 76713.0,
        "gpu_tot_sim_insn": 26560256.0,
        "gpu_tot_ipc": 346.2289,
        "sim_rate_ips": 510774.0
      }
    },
    {
      "sim": {
        "id": "sim-e8f63b6b3bed",
        "run_id": "run-210d75c008c4",
        "gpu_config": "SM86_RTX3070",
        "replica": 1,
        "state": "succeeded",
        "error": null,
        "launcher_ref": "64419",
        "created_at": "2026-11-08T08:59:03.024065Z",
        "started_at": "2026-11-08T08:59:03.224173Z",
        "finished_at": "2026-11-08T08:59:06.164567Z",
        "last_heartbeat_at": "2026-11-08T08:59:06.164567Z",
        "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 */
        ]
      },
      "trace_id": "demo",
      "gpu_config": {
        "name": "SM86_RTX3070",
        "arch": "sm_86",
        "core_clock_mhz": 1132.0
      },
      "kernels": [
        {
          "sim_id": "sim-e8f63b6b3bed",
          "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
            /* 945 more keys trimmed */
          }
        },
        {
          "sim_id": "sim-e8f63b6b3bed",
          "kernel_index": 1,
          "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
          "kernel_launch_uid": 2,
          "gpu_sim_cycle": 5923,
          "gpu_sim_insn": 11264,
          "gpu_ipc": 1.9017,
          "sim_time_ns": 5232.332155477032,
          "stats": {
            "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
            "kernel_launch_uid": 2.0,
            "gpu_sim_cycle": 5923.0,
            "gpu_sim_insn": 11264.0
            /* 950 more keys trimmed */
          }
        }
        /* 4 more items trimmed */
      ],
      "totals": {
        "gpu_tot_sim_cycle": 76713.0,
        "gpu_tot_sim_insn": 26560256.0,
        "gpu_tot_ipc": 346.2289,
        "sim_rate_ips": 510774.0
      }
    }
  ],
  "comparison": {
    "has_real_timing": false,
    "configs": [
      "SM86_RTX3070"
    ],
    "rows": [
      {
        "kernel_index": 0,
        "kernel_name": "_Z11init_kernelIdEvPT_S1_S1_S0_S0_S0_",
        "real_ns": null,
        "sim_ns": {
          "SM86_RTX3070": 5454.063604240282
        }
      },
      {
        "kernel_index": 1,
        "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
        "real_ns": null,
        "sim_ns": {
          "SM86_RTX3070": 5232.332155477032
        }
      }
      /* 4 more items trimmed */
    ]
  }
}

Download sim results#

GET/api/sims/{sim_id}/resultsbearer token

Returns one sim's results as a JSON download named <sim_id>-results.json. totals is the sim's latest SimMetrics.

Path parameters#

name	type	description
`sim_id`	`str`	The sim's `id`, such as `sim-6b4c91e71437`. Find it in `RunDetail.sims`.

Returns#

200 with a SimResults.

Errors#

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

Example#

bash

curl -OJ "$CASCADE_URL/api/sims/sim-1047ddbdf5b1/results" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/sims/sim-1047ddbdf5b1/results", headers=headers)
resp.raise_for_status()
open("sim-1047ddbdf5b1-results.json", "wb").write(resp.content)

const resp = await fetch(`${CASCADE_URL}/api/sims/sim-1047ddbdf5b1/results`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
const data = await resp.json();

Response · 200 OK · application/json

{
  "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 */
    ]
  },
  "trace_id": "demo",
  "gpu_config": {
    "name": "SM86_RTX3070",
    "arch": "sm_86",
    "core_clock_mhz": 1132.0
  },
  "kernels": [
    {
      "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
        /* 945 more keys trimmed */
      }
    },
    {
      "sim_id": "sim-1047ddbdf5b1",
      "kernel_index": 1,
      "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
      "kernel_launch_uid": 2,
      "gpu_sim_cycle": 5923,
      "gpu_sim_insn": 11264,
      "gpu_ipc": 1.9017,
      "sim_time_ns": 5232.332155477032,
      "stats": {
        "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
        "kernel_launch_uid": 2.0,
        "gpu_sim_cycle": 5923.0,
        "gpu_sim_insn": 11264.0
        /* 950 more keys trimmed */
      }
    }
    /* 4 more items trimmed */
  ],
  "totals": {
    "gpu_tot_sim_cycle": 76713.0,
    "gpu_tot_sim_insn": 26560256.0,
    "gpu_tot_ipc": 346.2289,
    "sim_rate_ips": 510774.0
  }
}

Download a sim's log#

GET/api/sims/{sim_id}/logbearer token

Streams every line the simulator sent, in seq order, as text/plain named <sim_id>.log.

Path parameters#

name	type	description
`sim_id`	`str`	The sim's `id`, such as `sim-6b4c91e71437`. Find it in `RunDetail.sims`.

Returns#

200 with the log as plain text.

Errors#

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

Example#

bash

curl -OJ "$CASCADE_URL/api/sims/sim-1047ddbdf5b1/log" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/sims/sim-1047ddbdf5b1/log", headers=headers)
resp.raise_for_status()
open("sim-1047ddbdf5b1.log", "wb").write(resp.content)

const resp = await fetch(`${CASCADE_URL}/api/sims/sim-1047ddbdf5b1/log`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
const text = await resp.text();

Response · 200 OK · text/plain

GPGPU-Sim version 4.2.0 (build gpgpu-sim_git-commit-13c67115070dc2f0876254a790d0238073ca364a-modified_590.0) configured with AccelWattch.

----------------------------------------------------------------------------
INFO - If you only care about PTX execution, ignore this message. GPGPU-Sim supports PTX execution in modern CUDA.
If you want to run PTXPLUS (sm_1x SASS) with a modern card configuration - set the envronment variable
$PTXAS_CUDA_INSTALL_PATH to point a CUDA version compabible with your card configurations (i.e. 8+ for PASCAL, 9+ for VOLTA etc..)
For example: "export $PTXAS_CUDA_INSTALL_PATH=/usr/local/cuda-9.1"

The following text describes why:
If you are using PTXPLUS, only sm_1x is supported and it requires that the app and simulator binaries are compiled in CUDA 4.2 or less.
The simulator requires it since CUDA headers desribe struct sizes in the exec which change from gen to gen.
The apps require 4.2 because new versions of CUDA tools have dropped parsing support for generating sm_1x
/* 10679 more lines trimmed */

List a run's output files#

GET/api/runs/{run_id}/filesbearer token

Lists the files every sim in the run uploaded, ordered by config, replica, then name. Each RunFile names its sim, so one call covers the run. cascade worker uploads a sim's files just before its final heartbeat, so the list grows as sims finish. Fetch one with Download an output file.

Path parameters#

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

Returns#

200 with a list of RunFile.

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 "$CASCADE_URL/api/runs/run-210d75c008c4/files" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4/files", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/runs/run-210d75c008c4/files`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

[
  {
    "name": "accelsim.log.gz",
    "size": 37105,
    "content_type": "application/gzip",
    "created_at": "2026-11-08T08:59:06.128163Z",
    "sim_id": "sim-1047ddbdf5b1",
    "gpu_config": "SM86_RTX3070",
    "replica": 0
  },
  {
    "name": "exit-status.txt",
    "size": 2,
    "content_type": "text/plain",
    "created_at": "2026-11-08T08:59:06.120587Z",
    "sim_id": "sim-1047ddbdf5b1",
    "gpu_config": "SM86_RTX3070",
    "replica": 0
  },
  {
    "name": "gpgpu_inst_stats.txt",
    "size": 133,
    "content_type": "text/plain",
    "created_at": "2026-11-08T08:59:06.121677Z",
    "sim_id": "sim-1047ddbdf5b1",
    "gpu_config": "SM86_RTX3070",
    "replica": 0
  },
  {
    "name": "kernel-stats.csv",
    "size": 3829,
    "content_type": "text/csv",
    "created_at": "2026-11-08T08:59:06.122701Z",
    "sim_id": "sim-1047ddbdf5b1",
    "gpu_config": "SM86_RTX3070",
    "replica": 0
  }
  /* 8 more items trimmed */
]

Download a Perfetto trace#

GET/api/runs/{run_id}/perfettobearer token

Builds a Chrome trace JSON from the run's parsed kernel stats and returns it with Content-Disposition: attachment; filename="<run_id>-perfetto.json". Each config is a process, each replica is a thread in it, and each finished kernel is one slice. The app builds it from the stats it parsed, so every run has one, whether or not the simulator wrote its own. Reading results describes the layout.

Path parameters#

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

Returns#

200 with a Chrome trace JSON object: traceEvents, displayTimeUnit and otherData.

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 -OJ "$CASCADE_URL/api/runs/run-210d75c008c4/perfetto" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/runs/run-210d75c008c4/perfetto", headers=headers)
resp.raise_for_status()
open("run-210d75c008c4-perfetto.json", "wb").write(resp.content)

const resp = await fetch(`${CASCADE_URL}/api/runs/run-210d75c008c4/perfetto`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
const data = await resp.json();

Response · 200 OK · application/json

{
  "traceEvents": [
    {
      "ph": "M",
      "pid": 1,
      "name": "process_name",
      "args": {
        "name": "SM86_RTX3070 · Accel-Sim simulated GPU"
      }
    },
    {
      "ph": "M",
      "pid": 1,
      "name": "process_sort_index",
      "args": {
        "sort_index": 1
      }
    },
    {
      "ph": "M",
      "pid": 1,
      "name": "thread_name",
      "args": {
        "name": "replica 0 · sim-1047ddbdf5b1"
      },
      "tid": 1
    },
    {
      "ph": "M",
      "pid": 1,
      "name": "thread_sort_index",
      "args": {
        "sort_index": 1
      },
      "tid": 1
    },
    {
      "ph": "X",
      "pid": 1,
      "tid": 1,
      "cat": "kernel",
      "name": "k1 init_kernel",
      "ts": 0.0,
      "dur": 5.454,
      "args": {
        "kernel_index": 0,
        "uid": 1,
        "kernel_name": "_Z11init_kernelIdEvPT_S1_S1_S0_S0_S0_",
        "gpu_sim_cycle": 6174,
        "gpu_sim_insn": 19456,
        "ipc": 3.1513,
        "sim_time_ns": 5454.063604240282,
        "start_cycle": 0,
        "end_cycle": 6174
      }
    },
    {
      "ph": "X",
      "pid": 1,
      "tid": 1,
      "cat": "kernel",
      "name": "k2 copy_kernel",
      "ts": 5.454,
      "dur": 5.232,
      "args": {
        "kernel_index": 1,
        "uid": 2,
        "kernel_name": "_Z11copy_kernelIdEvPKT_PS0_",
        "gpu_sim_cycle": 5923,
        "gpu_sim_insn": 11264,
        "ipc": 1.9017,
        "sim_time_ns": 5232.332155477032,
        "start_cycle": 6174,
        "end_cycle": 12097
      }
    }
    /* 12 more items trimmed */
  ],
  "displayTimeUnit": "ns",
  "otherData": {
    "run_id": "run-210d75c008c4",
    "trace_id": "demo",
    "time_axis": "simulated time, microseconds; each sim's kernels laid end to end",
    "slice_duration": "sim_time_ns = gpu_sim_cycle / core clock (MHz) * 1000",
    "kernel_scope": "sequential kernels, each including the configured launch latency; excludes host time and memcpy"
  }
}

List a sim's output files#

GET/api/sims/{sim_id}/filesbearer token

Lists one sim's uploaded files, sorted by name. The list is empty until the simulator uploads something.

Path parameters#

name	type	description
`sim_id`	`str`	The sim's `id`, such as `sim-6b4c91e71437`. Find it in `RunDetail.sims`.

Returns#

200 with a list of SimFile.

Errors#

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

Example#

bash

curl "$CASCADE_URL/api/sims/sim-1047ddbdf5b1/files" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/sims/sim-1047ddbdf5b1/files", headers=headers)
resp.raise_for_status()
print(resp.json())

const resp = await fetch(`${CASCADE_URL}/api/sims/sim-1047ddbdf5b1/files`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());

Response · 200 OK · application/json

[
  {
    "name": "accelsim.log.gz",
    "size": 37105,
    "content_type": "application/gzip",
    "created_at": "2026-11-08T08:59:06.128163Z"
  },
  {
    "name": "exit-status.txt",
    "size": 2,
    "content_type": "text/plain",
    "created_at": "2026-11-08T08:59:06.120587Z"
  },
  {
    "name": "gpgpu_inst_stats.txt",
    "size": 133,
    "content_type": "text/plain",
    "created_at": "2026-11-08T08:59:06.121677Z"
  },
  {
    "name": "kernel-stats.csv",
    "size": 3829,
    "content_type": "text/csv",
    "created_at": "2026-11-08T08:59:06.122701Z"
  },
  {
    "name": "opt125m_H100_perfetto.json.gz",
    "size": 104763,
    "content_type": "application/gzip",
    "created_at": "2026-11-08T08:59:06.123623Z"
  },
  {
    "name": "perf_counter.csv.gz",
    "size": 474373,
    "content_type": "application/gzip",
    "created_at": "2026-11-08T08:59:06.124946Z"
  }
]

Download an output file#

GET/api/sims/{sim_id}/files/{name}bearer token

Returns the file as a download named name, with the file's content_type. A .gz file comes back as application/gzip with no Content-Encoding, so it stays compressed.

Path parameters#

name	type	description
`sim_id`	`str`	The sim's `id`, such as `sim-6b4c91e71437`. Find it in `RunDetail.sims`.
`name`	`str`	The file's name, such as `kernel-stats.csv`. Letters, digits, `.`, `_` and `-`, 1 to 128 characters, and not `.` or `..`.

Returns#

200 with the file's bytes.

Errors#

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

Example#

bash

curl -OJ "$CASCADE_URL/api/sims/sim-1047ddbdf5b1/files/kernel-stats.csv" \
  -H "Authorization: Bearer $CASCADE_TOKEN"

python

import os

import httpx

headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/sims/sim-1047ddbdf5b1/files/kernel-stats.csv", headers=headers)
resp.raise_for_status()
open("kernel-stats.csv", "wb").write(resp.content)

const resp = await fetch(`${CASCADE_URL}/api/sims/sim-1047ddbdf5b1/files/kernel-stats.csv`, {
  headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
const text = await resp.text();

Response · 200 OK · text/csv

uid,name,gpu_sim_cycle,gpu_sim_insn,ipc
1,nvjet_sm90_hsh_64x8_64x16_4x1_v_bz_bias_TNT,10120,4765148,470.86442687747035
2,_ZN4vllm30reshape_and_cache_flash_kernelIttLNS_18Fp8KVCacheDataTypeE0EEEvPKT_S4_PT0_S6_PKlllllliiiPKfSA_i,7429,395584,53.24862027190739
3,_ZN7cutlass13device_kernelIN5flash20enable_sm90_or_laterINS1_16FlashAttnFwdSm90INS1_25CollectiveMainloopFwdSm90ILi2EN4cute5tupleIJNS5_1CILi1EEES8_S8_EEENS6_IJNS7_ILi64EEENS7_ILi192EEESA_EEELi64ENS_6half_tEfNS_4arch4Sm90ELb1ELb0ELb0ELb1ELb1ELb0ELb0ELb1ELb1ELb1ELb0ELb0ENS_10bfloat16_tELi1EEENS1_21CollectiveEpilogueFwdINS6_IJSA_SA_SB_EEES9_SD_SF_Li128ELb1ELb1ELb0ELb0ELi1EEENS1_36VarlenDynamicPersistentTileSchedulerILi64ELi192ELi128ELi128ELb0ELb1ELb1ELb1ELb0ELb1EEEEEEEEEvNT_6ParamsE,14142,5542420,391.9120350728327
4,_ZN2at6native29vectorized_elementwise_kernelILi4ENS0_11FillFunctorIiEESt5arrayIPcLm1EEEEviT0_T1_,5345,3078,0.5758652946679139
5,nvjet_sm90_hsh_64x8_64x16_4x1_v_bz_bias_TNT,8998,1588148,176.50011113580797
6,nvjet_sm90_hsh_64x8_64x16_4x1_v_bz_bias_TNT,8634,4762652,551.6159369932824
7,_ZN4vllm30reshape_and_cache_flash_kernelIttLNS_18Fp8KVCacheDataTypeE0EEEvPKT_S4_PT0_S6_PKlllllliiiPKfSA_i,7026,65760,9.359521776259607
8,_ZN7cutlass13device_kernelIN5flash20enable_sm90_or_laterINS1_16FlashAttnFwdSm90INS1_25CollectiveMainloopFwdSm90ILi2EN4cute5tupleIJNS5_1CILi1EEES8_S8_EEENS6_IJNS7_ILi64EEENS7_ILi192EEESA_EEELi64ENS_6half_tEfNS_4arch4Sm90ELb0ELb0ELb0ELb1ELb1ELb0ELb0ELb1ELb1ELb1ELb0ELb0ENS_10bfloat16_tELi1EEENS1_21CollectiveEpilogueFwdINS6_IJSA_SA_SB_EEES9_SD_SF_Li128ELb1ELb1ELb0ELb0ELi1EEENS1_36VarlenDynamicPersistentTileSchedulerILi64ELi192ELi128ELi128ELb0ELb1ELb1ELb0ELb0ELb1EEEEEEEEEvNT_6ParamsE,12302,5247952,426.59339944724434
9,_ZN2at6native29vectorized_elementwise_kernelILi4ENS0_11FillFunctorIiEESt5arrayIPcLm1EEEEviT0_T1_,5348,3078,0.5755422587883321
10,nvjet_sm90_hsh_64x8_64x16_4x1_v_bz_bias_TNT,8424,1588020,188.51139601139602
11,nvjet_sm90_hsh_64x8_64x16_4x1_v_bz_bias_TNT,8621,4766492,552.8931678459576
/* 9 more lines trimmed */

404 response, no such file · 404 Not Found · application/json

{
  "detail": "sim sim-1047ddbdf5b1 has no file 'nope.txt'"
}