Skip to main content
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:

Processing

Actively starting or running

Paused

Temporarily suspended

Awaiting

Waiting for user input

Terminal

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, 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
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

​
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 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 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 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.

API Reference

View the execution status API endpoint

Webhooks

Set up real-time status notifications

Error Handling

Learn about failure paths in workflows

SDKs

Use our TypeScript or Python SDKs