API reference
Traces
Traces arrive over S3, not over this API. These routes read what the app has registered. To add a trace, upload it to the S3 endpoint as described in Trace a workload.
List traces#
GET/api/tracesbearer token
Lists every trace the app has registered, in every state, newest first by created_at. A trace appears as soon as its first file lands in the bucket, so this list also shows uploads in progress.
Returns#
200 with a list of TraceSummary.
Errors#
| status | when |
|---|---|
401 | The Authorization header is missing, is not Bearer <token>, or the token is wrong. |
Example#
curl "$CASCADE_URL/api/traces" \
-H "Authorization: Bearer $CASCADE_TOKEN"import os
import httpx
headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/traces", headers=headers)
resp.raise_for_status()
print(resp.json())const resp = await fetch(`${CASCADE_URL}/api/traces`, {
headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());[
{
"id": "demo-failed",
"state": "failed",
"error": "profiler reported status 'failed' in metadata.json",
"created_at": "2026-11-08T08:59:02.590922Z",
"updated_at": "2026-11-08T08:59:02.592166Z",
"model": null,
"layers": [],
"source_gpu": null,
"trace_gpu_arch": "sm_86",
"suggested_sim_config": null,
"kernel_count": 0,
"bytes": 16650759,
"has_real_timing": false,
"has_step_timeline": false,
"sample": false
},
{
"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
},
{
"id": "sample__facebook_opt-125m__h100-e2e",
"state": "ready",
"error": null,
"created_at": "2026-11-08T06:19:57.515017Z",
"updated_at": "2026-11-08T06:19:57.515017Z",
"model": "facebook/opt-125m",
"layers": [
"step 0 (prefill)",
"step 2 (decode)",
"step 10 (decode)",
"step 26 (decode)"
],
"source_gpu": "NVIDIA H100 80GB HBM3",
"trace_gpu_arch": "sm_90",
"suggested_sim_config": "SM90_H100",
"kernel_count": 712,
"bytes": 13065268,
"has_real_timing": true,
"has_step_timeline": true,
"sample": true
}
]Get a trace#
GET/api/traces/{trace_id}bearer token
Returns one trace with the parsed metadata.json and every kernel launch read from the trace's stats_ctx_* files. kernels stays empty until the trace is ready.
Path parameters#
| name | type | description |
|---|---|---|
trace_id | str | The trace's id, which is the profiler's run name. |
Returns#
200 with a TraceDetail.
Errors#
| status | when |
|---|---|
401 | The Authorization header is missing, is not Bearer <token>, or the token is wrong. |
404 | No trace has this id. |
Example#
curl "$CASCADE_URL/api/traces/demo" \
-H "Authorization: Bearer $CASCADE_TOKEN"import os
import httpx
headers = {"Authorization": f"Bearer {os.environ['CASCADE_TOKEN']}"}
resp = httpx.get(f"{os.environ['CASCADE_URL']}/api/traces/demo", headers=headers)
resp.raise_for_status()
print(resp.json())const resp = await fetch(`${CASCADE_URL}/api/traces/demo`, {
headers: { Authorization: `Bearer ${CASCADE_TOKEN}` },
});
console.log(await resp.json());{
"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
},
{
"key": "accelsim-traces/demo/configs/trace.config",
"bytes": 1085
}
/* 24 more items trimmed */
],
"trace_gpu_arch": "sm_86",
"suggested_sim_config": "SM86_RTX3070"
},
"kernels": []
}{
"detail": "trace nope not found"
}