Skip to main content
POST
Start an AI analysis of a run
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

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 need platform: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).

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

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.

Required string length: 1 - 255

Path Parameters

runId
string
required
Minimum string length: 1

Response

The run's analysis thread

data
object
required

threadId is the run's analysis thread. created is true when this request started the analysis, false when the run already had one and nothing was started.

meta
object
required