Lifecycle

QUEUED → RUNNING → (AUTH_REQUIRED | PAUSED)* → (SUCCESS | FAILED | CANCELED)

Terminal states: SUCCESS, FAILED, CANCELED

QUEUED

The run was accepted and is waiting to start (e.g., executor capacity, scheduling window).

  • What you can do: Nothing required. You can abort queued runs.

  • Abort: DELETE /v1/runs/{runId}.

RUNNING

The platform is planning/executing the steps and streaming events (SSE).

  • What you can do: Observe via GET /v1/runs/{runId}/sse. Approvals or auth may pause progress.

AUTH_REQUIRED

The run is blocked on user authorization (e.g., missing OAuth).

  • Where to get the link: It’s provided in the SSE stream and under the events in the RunDto object.

  • What you should do: Surface that auth URL to the user and resume once completed. The run returns to RUNNING automatically.

PAUSED

Execution is waiting for an approval decision.

  • Approve/deny: GET /v1/runs/approval?token=... (one-time token).

  • Outcome: Approve → back to RUNNING. Deny → typically CANCELED.

CANCELED

The run was aborted (via API) or denied during approval. Final state.

  • How to cancel: Abort any running/queued run with DELETE /v1/runs/{runId}.

  • Next step: Recreate a new run if you want to restart.

FAILED

The plan or a step couldn’t complete. Final state.

  • What to check: HTTP status codes and event logs (tool errors, validation failures), stepsFinished, and the last event payload.

  • Next step: Fix the cause (auth, approvals, payloads, rate limits) and create a fresh run.

SUCCESS

All planned steps completed. Final state.

  • What you can do: Read result (if present) and any summary posted by your workflow (e.g., Slack/Email).

PreviousRequest & response at a glanceNextApprovals

Last updated