Start an AI analysis of a run
Starts an agent’s analysis of a run’s root cause and recovery, once per run. Requires permission platform:manage.
v2 compatibility notes
One analysis per run
POST /api/v2/runs/startAnalysis starts an AI analysis of a run: an agent reads the run and records its root cause, the affected steps and recommended recovery actions in the run’s analysis thread. The analysis calls a model, so it spends. A run has at most one analysis. When it already has one, nothing starts and the answer’s created is false.
The body is exactly { "id" }, the run’s id. The answer is { "id", "threadId", "created" }. The Forge Console’s run page shows the analysis.
Who may start one
You needplatform:manage at the platform scope. It is an elevated permission that no Forge agent holds, and a Personal key carries it only with the elevated scope. A run you cannot read (runs:read at its home and at every company it carries) answers 404 like a missing one. A same-key retry returns the recorded answer only while both still hold (see Idempotency).
Related
Authorizations
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255
