Workflow Runs

Track and monitor individual workflow executions

Overview

A workflow run represents a single execution instance of a workflow. When a job run executes, it creates individual workflow runs for each workflow in the job’s execution order. Workflow runs track the progress, status, and results of each workflow as it executes.

Workflow runs provide granular visibility into your data operations, allowing you to monitor individual workflow execution, identify issues, and access generated artifacts.

Key Concepts

Workflow Run Lifecycle

Each workflow run progresses through several states during execution:

• PENDING: Workflow run created (usually queued) but not yet started
• IN_PROGRESS: Workflow is currently executing
• AWAITING_USER_INPUT: Workflow requires user interaction (e.g., 2FA code)
• COMPLETED: Workflow finished successfully
• COMPLETED_WITH_NO_ACTION_TAKEN: Workflow completed but found no work to do
• FAILED: Workflow encountered an error and could not complete

Current State Tracking

The currentStateName field indicates which step within the workflow is currently executing. This provides granular progress information beyond the high-level status.

For example, in a multi-step data extraction workflow, the currentStateName could be:

• “navigating_to_employees_page”
• “extracting_employee_records”
• “downloading_csv”

Workflow Run Context

Each workflow run is associated with:

• Workflow ID: The workflow template being executed
• Job Run ID: The job run that initiated this workflow run (if applicable)
• Created By User ID: The user who initiated the execution
• Timestamps: Creation time, last update time, and completion time

Execution Isolation

Each workflow run operates independently with its own:

• Browser session state
• Execution context
• Generated artifacts
• Status tracking

This isolation ensures that concurrent workflow runs don’t interfere with each other.

API Operations

List Workflow Runs

List Workflow Runs

Retrieve workflow runs for your organization with pagination support

Get a Workflow Run

Get Workflow Run

Retrieve detailed information about a specific workflow run

Create a Workflow Run

Create Workflow Run

Initiate a workflow execution by creating a new workflow run

In most cases, workflow runs are created automatically by job runs. Direct workflow run creation is typically used for testing.

Relationship with Other Resources

• Workflows: The template that defines what the workflow run executes
• Job Runs: Creates and manages workflow runs for all workflows in a job
• Artifacts: Generated by workflow runs and linked via workflowRunId

Monitoring and Observability

Status Polling

For real-time monitoring, poll workflow run status periodically:

async function waitForWorkflowCompletion(workflowRunId) {
  while (true) {
    const workflowRun = await fetch(`/workflow-runs/${workflowRunId}`);
    const { status } = await workflowRun.json();
    
    if (['COMPLETED', 'FAILED', 'COMPLETED_WITH_NO_ACTION_TAKEN'].includes(status)) {
      return status;
    }
    
    await sleep(5000); // Poll every 5 seconds
  }
}

Webhook Integration

For event-driven monitoring, use webhooks to receive notifications when workflow runs complete or require input. See the Webhooks documentation for details.

Best Practices

Execution Monitoring

1. Poll Appropriately: Use reasonable polling intervals (5-10 seconds) to balance responsiveness and API load
2. Use Webhooks: Implement webhook handlers for event-driven notifications
3. Track State Changes: Log state transitions to understand workflow progression
4. Monitor Failures: Alert on failed workflow runs for prompt investigation

Schema Reference

See the API Reference for complete schema definitions and field descriptions for the Workflow Run resource.