# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolregistry.ai/basics/lifecycle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.