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

projectId

string

required

Filter runs by project ID

flowId

string

Filter runs by specific flow ID

status

array

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

Response

data

array

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

Show Flow Run Object

string

Unique identifier for the flow run

projectId

string

Project ID where the run occurred

flowId

string

ID of the flow that was executed

flowVersionId

string

Specific version of the flow that was executed

flowVersion

object

Flow version metadata

displayName

string

Name of the flow

status

enum

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

startTime

string

ISO 8601 timestamp when execution started

finishTime

string

ISO 8601 timestamp when execution completed

environment

enum

Execution environment: PRODUCTION or TESTING

triggeredBy

string

User or system that triggered the run

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.

steps

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

logsFileId

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

strategy

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

projectId

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

flowRunIds

array

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

excludeFlowRunIds

array

Run IDs to exclude from cancellation

flowId

string

Cancel all runs for a specific flow

status

array

Cancel runs with specific statuses: PAUSED, RUNNING

createdAfter

string

Cancel runs created after this timestamp

createdBefore

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

strategy

enum

required

Retry strategy: FROM_FAILED_STEP or ON_LATEST_VERSION

flowRunIds

array

Specific run IDs to retry

excludeFlowRunIds

array

Run IDs to exclude from retry

flowId

string

Retry all runs for a specific flow

status

array

Retry runs with specific statuses

failedStepName

string

Retry runs that failed at a specific step

createdAfter

string

Retry runs created after this timestamp

createdBefore

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

flowRunIds

array

Specific run IDs to archive

excludeFlowRunIds

array

Run IDs to exclude from archiving

flowId

string

Archive runs for a specific flow

status

array

Archive runs with specific statuses

failedStepName

string

Archive runs that failed at a specific step

createdAfter

string

Archive runs created after this timestamp

createdBefore

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

requestId

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`);

Flows API

Manage the flows that create these runs

Connections API

Manage connections used during execution

Overview

Endpoints

​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