GET /runs/{id}

Details #

This is a run's trace. Poll it after POST /macros/{id}/run until status is no longer queued or running.

curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:48080/runs/r_91c0d2

{
  "id": "r_91c0d2",
  "macroId": "m_4f2a9c",
  "firedBy": { "trigger": "hotkey", "event": { "app": "com.apple.Safari" } },
  "startedAt": "2026-10-24T09:14:02Z",
  "endedAt": "2026-10-24T09:14:03Z",
  "status": "failed",
  "dryRun": false,
  "steps": [
    { "stepId": "s1", "status": "ok", "startedAt": "2026-10-24T09:14:02Z", "ms": 3, "in": { "text": "DAY-412" }, "out": null },
    { "stepId": "s2", "status": "failed", "startedAt": "2026-10-24T09:14:02Z", "ms": 120, "note": "element not found" }
  ],
  "variablesAfter": { "key": "DAY-412" },
  "failure": { "stepId": "s2", "lookedFor": "button \"Send\"", "found": [], "suggestion": "Pick the element again" }
}

Parameters #

curl --unix-socket "$SWITCHBOARD_HOME/engine.sock" -X GET http://localhost/runs/{id}

One run with its step-by-step trace. The Unix socket needs no token; loopback 127.0.0.1:48080 needs Authorization: Bearer <api-token>.

Gotchas #

• 404 with no run <id> when the run is unknown or was pruned.

• Over loopback every request needs Authorization: Bearer <token>; see GET /macros.

See also #

• GET /runs

• switchboard trace