Start a new ActionFlows flow execution via the REST API by triggering a run with a payload. Includes request body, options, and response schema.

Trigger Run

Start a new flow execution by triggering a run with a payload.

Endpoint

POST /api/runs

Try it

Live requests run from your browser. Open the API Explorer to try every operation from one screen.

post/api/runs

Trigger a run

Requests go to the live API from your browser. The docs server never sees this key.

This request can create, change, or cancel real work.

API key

X-Locale

JSON body

curl -X POST 'https://api.actionflows.ai/api/runs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Response

Send a request to see the response.

Authentication

Required. See API Reference for authentication details.

Request Body

{
  "payload": {
    "organizationId": "org_123",
    "actionFlowId": "flow_123",
    "inputs": {
      "node_abc_prompt": "Hello"
    },
    "trigger": {
      "body": { "hello": "world" },
      "headers": { "content-type": "application/json" },
      "method": "POST",
      "query": {}
    },
    "triggerSource": "api"
  },
  "idempotencyKey": "optional-unique-key",
  "delay": "5m",
  "tags": ["production", "api-triggered"],
  "maxAttempts": 3,
  "maxDuration": 3600
}

When the org concurrency limit is reached, the API responds with 202 and a queueId instead of an immediate Trigger run id.

Request Fields

Field	Type	Required	Description
`payload`	object	Yes	Run payload containing flow information and data
`payload.organizationId`	string	Yes	Organization ID that owns the flow
`payload.actionFlowId`	string	Yes	Flow ID to execute
`payload.inputs`	object	No	Per-run input overrides keyed as `{nodeId}_{inputName}` (same as the Actionflow Studio Flow inputs form)
`payload.trigger`	object	No	Incoming trigger envelope (`body`, `headers`, `method`, `query`) merged onto the start node
`payload.triggerSource`	string	No	How the run was started: `api`, `manual`, `webhook`, `schedule`, `subflow`, or `unknown`
`idempotencyKey`	string	No	Unique key to prevent duplicate runs
`delay`	string	No	Delay before starting the run (for example, `5m`, `1h`, `30s`)
`tags`	array	No	Tags to associate with the run
`maxAttempts`	number	No	Maximum number of retry attempts
`maxDuration`	number	No	Maximum duration in seconds

Response

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": "run_123",
    "status": "WAITING",
    "taskIdentifier": "run-flow",
    "payload": {
      "organizationId": "org_123",
      "actionFlowId": "flow_123"
    },
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Queued Response (202 Accepted)

When the organization concurrency limit is reached, the run is enqueued instead of starting immediately:

{
  "success": true,
  "data": {
    "status": "queued",
    "queueId": "queue_123",
    "runHistoryId": "runhist_123"
  }
}

Poll GET /api/runs/queue/[queueId] or list GET /api/runs/queue until the item is dispatched.

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Invalid request body",
  "issues": [
    {
      "path": ["payload", "organizationId"],
      "message": "Required"
    }
  ]
}

400 Bad Request - Flow Validation Failed

{
  "success": false,
  "error": "Flow validation failed",
  "message": "Flow validation failed",
  "validationErrors": [
    "Error message 1",
    "Error message 2"
  ],
  "validationWarnings": [
    "Warning message 1"
  ]
}

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "message": "Authentication required"
}

404 Not Found

{
  "success": false,
  "error": "Flow not found",
  "message": "Flow not found",
  "messageParams": {
    "actionFlowId": "flow_123",
    "organizationId": "org_123"
  }
}

429 Too Many Requests

{
  "error": "Too many requests"
}

Example Requests

Basic Trigger

curl -X POST https://api.actionflows.ai/api/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "organizationId": "org_123",
      "actionFlowId": "flow_123",
      "data": {
        "customerEmail": "[email protected]",
        "message": "Hello, I need help"
      }
    }
  }'

Trigger with Options

curl -X POST https://api.actionflows.ai/api/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "organizationId": "org_123",
      "actionFlowId": "flow_123",
      "data": {
        "customerEmail": "[email protected]"
      }
    },
    "idempotencyKey": "unique-key-123",
    "tags": ["production", "api"],
    "maxAttempts": 3,
    "maxDuration": 3600
  }'

JavaScript

// Basic trigger
const response = await fetch('https://api.actionflows.ai/api/runs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payload: {
      organizationId: 'org_123',
      actionFlowId: 'flow_123',
      data: {
        customerEmail: '[email protected]',
        message: 'Hello, I need help',
      },
    },
  }),
});

const data = await response.json();

if (data.success) {
  console.log('Run triggered:', data.data.id);
  console.log('Status:', data.data.status);
} else {
  console.error('Error:', data.error);
  
  if (data.validationErrors) {
    console.error('Validation errors:', data.validationErrors);
  }
}

// Trigger with options
const responseWithOptions = await fetch('https://api.actionflows.ai/api/runs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payload: {
      organizationId: 'org_123',
      actionFlowId: 'flow_123',
      data: {
        customerEmail: '[email protected]',
      },
    },
    idempotencyKey: `run-${Date.now()}`,
    tags: ['production', 'api'],
    maxAttempts: 3,
    maxDuration: 3600,
  }),
});

Python

import requests
import json

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

# Basic trigger
payload = {
    'payload': {
        'organizationId': 'org_123',
        'actionFlowId': 'flow_123',
        'data': {
            'customerEmail': '[email protected]',
            'message': 'Hello, I need help',
        },
    },
}

response = requests.post(
    'https://api.actionflows.ai/api/runs',
    headers=headers,
    json=payload
)

data = response.json()

if data['success']:
    print(f"Run triggered: {data['data']['id']}")
    print(f"Status: {data['data']['status']}")
else:
    print(f"Error: {data['error']}")
    if 'validationErrors' in data:
        print(f"Validation errors: {data['validationErrors']}")

# Trigger with options
payload_with_options = {
    'payload': {
        'organizationId': 'org_123',
        'actionFlowId': 'flow_123',
        'data': {
            'customerEmail': '[email protected]',
        },
    },
    'idempotencyKey': f'run-{int(time.time())}',
    'tags': ['production', 'api'],
    'maxAttempts': 3,
    'maxDuration': 3600,
}

response_with_options = requests.post(
    'https://api.actionflows.ai/api/runs',
    headers=headers,
    json=payload_with_options
)

Delay Format

The delay parameter accepts time strings in the following formats:

30s - 30 seconds
5m - 5 minutes
1h - 1 hour
2d - 2 days

Flow Validation

Before triggering a run, the flow is automatically validated. If validation fails, you'll receive a 400 Bad Request response with validation errors and warnings.

Common validation errors:

Missing required nodes
Invalid node connections
Missing integration credentials
Disabled nodes

Idempotency

Use the idempotencyKey parameter to prevent duplicate runs. If a run with the same idempotency key already exists, the API will return the existing run instead of creating a new one.

Notes

The flow must exist and be accessible to your organization
The flow is validated before execution
Validation warnings don't prevent execution but should be reviewed
This endpoint is rate-limited per user
Use tags to organize and filter runs
The maxDuration is specified in seconds

Getting Required IDs

To trigger a run, you need the organizationId and actionFlowId. You can get these values from:

List Flows endpoint (GET /api/actionflows) - Returns all flows with their id and organizationId
Get Flow endpoint (GET /api/actionflows/{actionFlowId}) - Returns a specific flow with its id and organizationId

Example workflow:

Call GET /api/actionflows to list all available flows
Find the flow you want to trigger and note its id (this is the actionFlowId) and organizationId
Use these values in the trigger request payload

Trigger Run

Try it

On this page