Flow Runs API - Activepieces

Overview

The Flow Runs API allows you to trigger flow executions, retrieve run details, monitor execution status, and manage running flows. Flow runs represent individual executions of your automation flows.

Base Endpoint

GET    /api/v1/flow-runs
GET    /api/v1/flow-runs/:id
POST   /api/v1/flow-runs/:id/retry
POST   /api/v1/flow-runs/cancel
POST   /api/v1/flow-runs/retry
POST   /api/v1/flow-runs/archive

List Flow Runs

Retrieve a paginated list of flow runs with optional filters.

curl https://cloud.activepieces.com/api/v1/flow-runs?projectId=project_123&limit=20 \
  -H "Authorization: Bearer sk-your-api-key"

Query Parameters

string

required

Filter runs by project ID

string

Filter runs by specific flow ID

array

Filter by run status. Multiple values allowed.Values: RUNNING, SUCCEEDED, FAILED, PAUSED, QUOTA_EXCEEDED, INTERNAL_ERROR, TIMEOUT, STOPPED

array

Filter runs by tags

string

Filter runs that failed at a specific step

string

ISO 8601 timestamp - Filter runs created after this time

string

ISO 8601 timestamp - Filter runs created before this time

array

Filter by specific run IDs

boolean

default:"false"

Include archived runs in the results

number

default:"10"

Number of runs to return (1-100)

string

Pagination cursor from previous response

Response

array

Array of flow run objects (without step details for list view)

Show Flow Run Object

string

Unique identifier for the flow run

string

Project ID where the run occurred

string

ID of the flow that was executed

string

Specific version of the flow that was executed

object

Flow version metadata

string

Name of the flow

enum

Execution status: RUNNING, SUCCEEDED, FAILED, PAUSED, QUOTA_EXCEEDED, INTERNAL_ERROR, TIMEOUT, STOPPED

string

ISO 8601 timestamp when execution started

string

ISO 8601 timestamp when execution completed

enum

Execution environment: PRODUCTION or TESTING

string

User or system that triggered the run

array

Tags associated with the run

object

Information about the failed step if status is FAILED

string

Internal name of the failed step

string

Display name of the failed step

number

Total number of steps executed

string

ISO 8601 timestamp when run was archived (null if not archived)

string

Cursor for next page (null if no more results)

string

Cursor for previous page (null if on first page)

Response Example

{
  "data": [
    {
      "id": "run_abc123",
      "projectId": "project_123",
      "flowId": "flow_xyz789",
      "flowVersionId": "version_456",
      "flowVersion": {
        "displayName": "Customer Onboarding"
      },
      "status": "SUCCEEDED",
      "startTime": "2024-01-15T10:30:00.000Z",
      "finishTime": "2024-01-15T10:30:15.000Z",
      "environment": "PRODUCTION",
      "triggeredBy": "user_789",
      "tags": ["onboarding", "customer"],
      "stepsCount": 5,
      "archivedAt": null,
      "created": "2024-01-15T10:30:00.000Z"
    }
  ],
  "next": "eyJpZCI6InJ1bl9hYmMxMjMifQ==",
  "previous": null
}

Get Flow Run

Retrieve detailed information about a specific flow run, including step execution data.

curl https://cloud.activepieces.com/api/v1/flow-runs/run_abc123 \
  -H "Authorization: Bearer sk-your-api-key"

Path Parameters

string

required

The flow run ID

Response

Returns the complete flow run object including step-by-step execution data.

object

Dictionary of step execution results, keyed by step name. Contains input data, output data, duration, and status for each executed step.

Step data may be missing if:

The run has not started yet
The run is older than AP_EXECUTION_DATA_RETENTION_DAYS and data has been purged

string

ID of the file containing execution logs

Response Example

{
  "id": "run_abc123",
  "projectId": "project_123",
  "flowId": "flow_xyz789",
  "status": "SUCCEEDED",
  "startTime": "2024-01-15T10:30:00.000Z",
  "finishTime": "2024-01-15T10:30:15.000Z",
  "environment": "PRODUCTION",
  "steps": {
    "trigger": {
      "type": "WEBHOOK",
      "output": { /* webhook payload */ },
      "duration": 50
    },
    "send_email": {
      "type": "ACTION",
      "input": { /* action input */ },
      "output": { /* action output */ },
      "status": "SUCCEEDED",
      "duration": 1200
    }
  },
  "logsFileId": "file_logs_123"
}

Retry Flow Run

Retry a failed or stopped flow run.

curl -X POST https://cloud.activepieces.com/api/v1/flow-runs/run_abc123/retry \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "FROM_FAILED_STEP",
    "projectId": "project_123"
  }'

Path Parameters

string

required

The flow run ID to retry

Request Body

enum

required

Retry strategy to use:

FROM_FAILED_STEP - Resume from the failed step, preserving previous step outputs
ON_LATEST_VERSION - Restart the entire flow using the latest published version

string

required

Project ID (for authorization)

Response

Returns the new flow run object created by the retry operation.

Retry Strategies Explained:

FROM_FAILED_STEP: Efficient for transient failures. Reuses successful step outputs and only re-executes from the point of failure.
ON_LATEST_VERSION: Useful when you’ve fixed the flow definition. Starts fresh with the latest flow version.

Bulk Cancel Flow Runs

Cancel multiple paused or queued flow runs at once.

curl -X POST https://cloud.activepieces.com/api/v1/flow-runs/cancel \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "flowId": "flow_xyz789",
    "status": ["PAUSED", "RUNNING"]
  }'

Request Body

array

Specific run IDs to cancel. If provided, other filters are ignored.

array

Run IDs to exclude from cancellation

string

Cancel all runs for a specific flow

array

Cancel runs with specific statuses: PAUSED, RUNNING

string

Cancel runs created after this timestamp

string

Cancel runs created before this timestamp

Response

{
  "cancelled": 5
}

Bulk Retry Flow Runs

Retry multiple failed flow runs at once.

curl -X POST https://cloud.activepieces.com/api/v1/flow-runs/retry \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "flowId": "flow_xyz789",
    "strategy": "FROM_FAILED_STEP",
    "status": ["FAILED"],
    "createdAfter": "2024-01-15T00:00:00.000Z"
  }'

Request Body

enum

required

Retry strategy: FROM_FAILED_STEP or ON_LATEST_VERSION

array

Specific run IDs to retry

array

Run IDs to exclude from retry

string

Retry all runs for a specific flow

array

Retry runs with specific statuses

string

Retry runs that failed at a specific step

string

Retry runs created after this timestamp

string

Retry runs created before this timestamp

Response

{
  "retried": 12
}

Bulk Archive Flow Runs

Archive multiple flow runs to clean up your run history.

curl -X POST https://cloud.activepieces.com/api/v1/flow-runs/archive \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "flowId": "flow_xyz789",
    "status": ["SUCCEEDED"],
    "createdBefore": "2024-01-01T00:00:00.000Z"
  }'

Request Body

Accepts the same filters as bulk retry (except strategy).

array

Specific run IDs to archive

array

Run IDs to exclude from archiving

string

Archive runs for a specific flow

array

Archive runs with specific statuses

string

Archive runs that failed at a specific step

string

Archive runs created after this timestamp

string

Archive runs created before this timestamp

Response

{
  "archived": 150
}

Archived runs are not deleted but are excluded from default list queries unless includeArchived=true is specified.

Resume Paused Run (Human Input)

Resume a paused flow run that’s waiting for human input.

curl -X POST https://cloud.activepieces.com/api/v1/flow-runs/run_abc123/requests/req_xyz/sync \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "comments": "Looks good!"
  }'

Path Parameters

string

required

The flow run ID

string

required

The request ID for the human input step

Request Body

The body should contain the response data expected by the human input step.

Response

Returns the step’s response after processing the input. For synchronous requests (/sync endpoint), returns the output immediately.

Flow Run Status

Status Types

Status	Description
`RUNNING`	Flow is currently executing
`SUCCEEDED`	Flow completed successfully
`FAILED`	Flow failed during execution
`PAUSED`	Flow is waiting for human input or approval
`QUOTA_EXCEEDED`	Flow stopped due to quota limits
`INTERNAL_ERROR`	Internal system error occurred
`TIMEOUT`	Flow exceeded maximum execution time
`STOPPED`	Flow was manually stopped

Run Environments

PRODUCTION - Live executions triggered by real events
TESTING - Test runs triggered from the flow builder

Nested Flow Runs

Flows can trigger other flows, creating parent-child relationships.

Headers for Nested Runs

Header	Description
`ap-parent-run-id`	ID of the parent flow run
`ap-fail-parent-on-failure`	If `true`, parent run fails when child fails

curl -X POST https://cloud.activepieces.com/api/v1/flows/flow_xyz/run \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "ap-parent-run-id: run_parent123" \
  -H "ap-fail-parent-on-failure: true" \
  -H "Content-Type: application/json" \
  -d '{ /* trigger payload */ }'

Data Retention

Flow run execution data (steps, logs) is retained for a configurable period defined by AP_EXECUTION_DATA_RETENTION_DAYS. After this period:

Run metadata (status, timestamps) is preserved
Step execution data is purged
Logs are removed

This helps manage storage costs for high-volume automations.

Error Responses

Run Not Found (404)

{
  "statusCode": 404,
  "code": "ENTITY_NOT_FOUND",
  "params": {
    "entityType": "flow_run",
    "entityId": "run_abc123",
    "message": "Flow run not found"
  }
}

Best Practices

Monitoring Runs

Use tags to categorize and filter runs
Set up alerts for failed runs
Regularly review failedStepName to identify problematic steps
Monitor stepsCount and execution duration for performance

Retry Strategy

Use FROM_FAILED_STEP for transient failures (network issues, rate limits)
Use ON_LATEST_VERSION after fixing flow logic
Implement exponential backoff for bulk retries
Consider max retry limits to avoid infinite loops

Data Management

Archive old successful runs to improve query performance
Use date filters to query recent runs
Export important run data before retention period expires
Use pagination cursors for large result sets

Performance

Filter by flowId to reduce result set size
Use includeArchived=false (default) for faster queries
Avoid retrieving step data unless necessary
Cache run statuses when polling

Code Examples

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://cloud.activepieces.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.ACTIVEPIECES_API_KEY}`
  }
});

// List recent failed runs
const { data } = await client.get('/flow-runs', {
  params: {
    projectId: 'project_123',
    status: ['FAILED'],
    limit: 50
  }
});

console.log(`Found ${data.data.length} failed runs`);

// Retry all failed runs from last 24 hours
const yesterday = new Date(Date.now() - 86400000).toISOString();

const retryResult = await client.post('/flow-runs/retry', {
  flowId: 'flow_xyz789',
  strategy: 'FROM_FAILED_STEP',
  status: ['FAILED'],
  createdAfter: yesterday
});

console.log(`Retried ${retryResult.data.retried} runs`);

import requests
import os
from datetime import datetime, timedelta

API_KEY = os.environ['ACTIVEPIECES_API_KEY']
BASE_URL = 'https://cloud.activepieces.com/api/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# List recent failed runs
response = requests.get(
    f'{BASE_URL}/flow-runs',
    headers=headers,
    params={
        'projectId': 'project_123',
        'status': ['FAILED'],
        'limit': 50
    }
)

runs = response.json()
print(f"Found {len(runs['data'])} failed runs")

# Retry all failed runs from last 24 hours
yesterday = (datetime.now() - timedelta(days=1)).isoformat()

retry_response = requests.post(
    f'{BASE_URL}/flow-runs/retry',
    headers=headers,
    json={
        'flowId': 'flow_xyz789',
        'strategy': 'FROM_FAILED_STEP',
        'status': ['FAILED'],
        'createdAfter': yesterday
    }
)

print(f"Retried {retry_response.json()['retried']} runs")

Flows API

Manage the flows that create these runs

Connections API

Manage connections used during execution

​Overview

​Base Endpoint

​List Flow Runs

​Query Parameters

​Response

​Get Flow Run

​Path Parameters

​Response

​Retry Flow Run

​Path Parameters

​Request Body

​Response

​Bulk Cancel Flow Runs

​Request Body

​Response

​Bulk Retry Flow Runs

​Request Body

​Response

​Bulk Archive Flow Runs

​Request Body

​Response

​Resume Paused Run (Human Input)

​Path Parameters

​Request Body

​Response

​Flow Run Status

​Status Types

​Run Environments

​Nested Flow Runs

​Headers for Nested Runs

​Data Retention

​Error Responses

​Run Not Found (404)

​Best Practices

​Code Examples

​Related Endpoints

Flows API

Connections API

Overview

Base Endpoint

List Flow Runs

Query Parameters

Response

Get Flow Run

Path Parameters

Response

Retry Flow Run

Path Parameters

Request Body

Response

Bulk Cancel Flow Runs

Request Body

Response

Bulk Retry Flow Runs

Request Body

Response

Bulk Archive Flow Runs

Request Body

Response

Resume Paused Run (Human Input)

Path Parameters

Request Body

Response

Flow Run Status

Status Types

Run Environments

Nested Flow Runs

Headers for Nested Runs

Data Retention

Error Responses

Run Not Found (404)

Best Practices

Code Examples

Related Endpoints