> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Execution Statuses
> Understanding the lifecycle of agent executions
When you execute an agent, it progresses through various **statuses** that track its lifecycle from initiation to completion. Understanding these statuses helps you monitor execution state, handle errors gracefully, and build robust automation workflows.
Execution statuses fall into four main categories:
Actively starting or running
Temporarily suspended
Waiting for user input
Finished (final states)
***
## Status Types
### Processing Statuses
These statuses indicate that the execution is actively being processed or is in the process of starting.
#### `starting`
The execution has been initiated but hasn't begun actual processing yet. This is the initial state when you trigger an agent execution.
**Can transition to:** `running`, `failed`, `cancelled`, `completed`
#### `running`
The execution is actively processing and executing agent logic. The agent is navigating pages, interacting with elements, or making decisions.
**Can transition to:** `paused`, `paused_by_agent`, `cancelled`, `awaiting_confirmation`, `completed`, `failed`
***
### Paused Statuses
These statuses indicate that execution has been temporarily suspended and can be resumed later.
#### `paused`
The execution has been paused by user request. This is useful when you need to temporarily halt an execution without cancelling it entirely.
**Can transition to:** `cancelled`, `running`
User-initiated pauses allow you to safely suspend execution and resume later without losing progress.
#### `paused_by_agent`
The execution has been paused by the agent itself, typically when waiting for some condition or resource to become available.
**Can transition to:** `cancelled`, `running`, `failed`
**Timeout Considerations:** If an execution remains paused by the agent beyond the configured timeout period, it will timeout and transition to a `failed` state.
***
### Awaiting Statuses
#### `awaiting_confirmation`
The execution is waiting for user confirmation before proceeding. This status is used when the agent needs explicit user approval to continue with a sensitive or important action.
**Can transition to:** `completed`, `cancelled`, `failed`, `running`
Use awaiting confirmation for critical operations that require human oversight, such as financial transactions or data deletions.
***
### Terminal Statuses
These statuses indicate that the execution has finished and **cannot transition to any other state**. They represent the final outcome of an execution.
#### `completed`
The execution finished successfully. The agent completed all its tasks and reached an Output node with a success outcome.
**Can transition to:** None (terminal state)
#### `failed`
The execution encountered an error and could not complete. This could be due to unexpected page states, missing elements, timeouts, or other runtime errors.
**Can transition to:** None (terminal state)
#### `cancelled`
The execution was cancelled by user request or system intervention. Work stopped before completion.
**Can transition to:** None (terminal state)
**Terminal states are immutable.** Once an execution reaches `completed`, `failed`, or `cancelled`, it cannot be resumed or modified. You must start a new execution to retry.
***
## State Transitions
The status system enforces a **strict state machine** to maintain data integrity and ensure executions follow valid lifecycle paths.
### Valid Transition Rules
```mermaid theme={null}
graph TB
starting[starting]
running[running]
paused[paused]
paused_by_agent[paused_by_agent]
awaiting[awaiting_confirmation]
completed[completed]
failed[failed]
cancelled[cancelled]
starting --> running
starting --> failed
starting --> cancelled
starting --> completed
running --> paused
running --> awaiting
running --> completed
running --> failed
running --> cancelled
paused --> running
paused --> cancelled
paused_by_agent --> running
paused_by_agent --> cancelled
awaiting --> running
awaiting --> completed
awaiting --> failed
awaiting --> cancelled
style completed fill:#dcfce7
style failed fill:#fee2e2
style cancelled fill:#fef3c7
style running fill:#dbeafe
style starting fill:#e0e7ff
```
### Key Transition Constraints
1. **Terminal states are final** – Once an execution reaches `completed`, `failed`, or `cancelled`, it cannot transition to any other state.
2. **Starting is flexible** – From `starting`, the execution typically moves to `running`, but can go directly to terminal states if initialization fails or is cancelled.
3. **Running is the hub** – The `running` state is the most flexible and can transition to paused states, awaiting confirmation, or any terminal state.
***
## User-Initiated Status Changes
You can control execution flow by updating the execution status through the API.
### Pause
Pausing an execution temporarily suspends it, allowing you to inspect its current state or coordinate with other systems. The execution can be resumed later from where it left off.
**When to use:**
* Need to temporarily halt execution
* Want to inspect current state before continuing
* Coordinating with other systems or processes
### Resume
Resume a paused execution to continue processing from where it stopped.
### Cancel
Cancelling an execution stops it permanently and transitions it to a terminal state. **Cancel requests take priority over pause requests.**
**When to use:**
* Execution is no longer needed
* Detected an error condition
* User wants to stop the automation
If a pause request is pending and you issue a cancel request, the cancel will take priority and the execution will be cancelled instead of paused.
See the [API Reference](/api-reference/overview) for details on updating execution status.
***
## Monitoring Execution Status
There are two primary ways to monitor execution status:
### Polling for Status Updates
You can poll the execution status endpoint to monitor progress. Check the status field to determine if the execution is still processing, has completed, or encountered an error.
**Status categories for monitoring:**
* **Processing**: `starting`, `running`
* **Paused**: `paused`, `paused_by_agent`
* **Awaiting**: `awaiting_confirmation`
* **Terminal**: `completed`, `failed`, `cancelled`
See the [API Reference](/api-reference/overview) for details on the execution status endpoint.
### Webhook Notifications
For real-time status updates, configure webhooks to receive notifications when execution status changes. This is more efficient than polling, especially for long-running executions.
Learn more about webhooks in the [Integrations](/fundamentals/integrations/webhooks) section.
***
## Best Practices
### 1. Always Check Status Before Operations
Before attempting to send messages or modify an execution, verify it's not in a terminal state. Operations on completed, failed, or cancelled executions will fail.
### 2. Handle All Terminal States
When monitoring executions, handle all three terminal states appropriately:
* **`completed`**: Extract results and proceed with your workflow
* **`failed`**: Log the error, trigger retry logic, or send alerts
* **`cancelled`**: Clean up resources and notify relevant systems
### 3. Distinguish Between Pause Types
Track whether a pause was user-initiated or agent-initiated for proper UI/UX:
* **`paused`**: User-initiated - show "Resume" controls
* **`paused_by_agent`**: Agent-initiated - display "Agent is waiting..." message
### 4. Set Appropriate Timeouts
When polling for status, implement timeout logic to avoid indefinite waiting. Consider the expected duration of your automation when setting timeouts.
### 5. Use Webhooks for Long-Running Executions
For executions that may take several minutes or hours, use webhooks instead of polling to avoid unnecessary API calls and improve efficiency.
***
## Related Resources
View the execution status API endpoint
Set up real-time status notifications
Learn about failure paths in workflows
Use our TypeScript or Python SDKs