Trigger and poll automations

Call POST /ai/trigger to run automations that match a trigger source. This example assumes the project already has an automation configured with the endpoint source. For a named webhook, configure a webhook automation first and replace endpoint below with its exact webhook name. Use the authentication variables from the quickstart and set PROJECT_ID to the target project. cURL uses Bash and jq; Python uses requests; JavaScript uses Node.js 22 or later with .mjs files. Trigger endpoints are under /ai, with project_id in the request body.

Start the runs

Send wait: false so the API returns run IDs while execution continues. context carries the JSON input your configured automations expect; the example provides a message.

set -euo pipefail

jq -n --arg project "$PROJECT_ID" '{
  project_id: $project,
  source: "endpoint",
  context: {
    message: "Run the configured automation check"
  },
  wait: false
}' > trigger.json

curl --fail-with-body --silent --show-error \
  "$FLOW_API_URL/ai/trigger" \
  -H "X-API-Key: $FLOW_API_KEY" \
  -H "customer: $FLOW_CUSTOMER" \
  -H "Content-Type: application/json" \
  --data-binary @trigger.json \
  -o trigger-response.json

jq '.results[] | {agent_id, automation_id, automation_name, status}' \
  trigger-response.json

import os
import json
import requests

base_url = os.environ["FLOW_API_URL"].rstrip("/")
headers = {"X-API-Key": os.environ["FLOW_API_KEY"], "customer": os.environ["FLOW_CUSTOMER"]}

payload = {
    "project_id": os.environ["PROJECT_ID"],
    "source": "endpoint",
    "context": {"message": "Run the configured automation check"},
    "wait": False,
}

response = requests.post(
    f"{base_url}/ai/trigger", headers=headers, timeout=30,
    json=payload
)
response.raise_for_status()
data = response.json()
with open("trigger-response.json", "w") as output:
    json.dump(data, output, indent=2)
for run in data["results"]:
    print(json.dumps({key: run[key] for key in ("agent_id", "automation_id", "automation_name", "status")}))

const baseUrl = process.env.FLOW_API_URL.replace(/\/$/, "");
const headers = {
  "X-API-Key": process.env.FLOW_API_KEY,
  customer: process.env.FLOW_CUSTOMER,
};

import { writeFile } from "node:fs/promises";
const payload = {
  project_id: process.env.PROJECT_ID,
  source: "endpoint",
  context: { message: "Run the configured automation check" },
  wait: false,
};

const url = new URL(`${baseUrl}/ai/trigger`);
const response = await fetch(url, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
await writeFile("trigger-response.json", JSON.stringify(data, null, 2));
for (const { agent_id, automation_id, automation_name, status } of data.results) {
  console.log({ agent_id, automation_id, automation_name, status });
}

An asynchronous request returns HTTP 202. results contains one entry per matched automation, with its agent_id and current status. An empty results array means there are no matched runs to poll. Check the project’s configured source before sending another trigger. A trigger can match multiple automations. Always include project_id to scope the request to the intended project.

Poll by run ID

Copy an agent_id from the trigger response. Polling accepts up to 50 comma-separated run IDs per request.

export AGENT_IDS="run-id-from-trigger-response"

curl --fail-with-body --silent --show-error --get \
  "$FLOW_API_URL/ai/trigger/runs" \
  -H "X-API-Key: $FLOW_API_KEY" \
  -H "customer: $FLOW_CUSTOMER" \
  --data-urlencode "agent_ids=$AGENT_IDS" \
  | jq '.items[] | {
      agent_id, status, integration_response,
      integration_grade, branches, error
    }'

import os
import json
import requests

base_url = os.environ["FLOW_API_URL"].rstrip("/")
headers = {"X-API-Key": os.environ["FLOW_API_KEY"], "customer": os.environ["FLOW_CUSTOMER"]}

response = requests.get(
    f"{base_url}/ai/trigger/runs", headers=headers, timeout=30,
    params={"agent_ids": os.environ["AGENT_IDS"]}
)
response.raise_for_status()
data = response.json()
for run in data["items"]:
    print(json.dumps({key: run.get(key) for key in ("agent_id", "status", "integration_response", "integration_grade", "branches", "error")}))

const baseUrl = process.env.FLOW_API_URL.replace(/\/$/, "");
const headers = {
  "X-API-Key": process.env.FLOW_API_KEY,
  customer: process.env.FLOW_CUSTOMER,
};

const url = new URL(`${baseUrl}/ai/trigger/runs`);
url.search = new URLSearchParams({ agent_ids: process.env.AGENT_IDS }).toString();
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
for (const { agent_id, status, integration_response, integration_grade, branches, error } of data.items) {
  console.log({ agent_id, status, integration_response, integration_grade, branches, error });
}

The poll response uses items, rather than the trigger response’s results.

Status	Action
`running`	Poll again after a delay.
`completed`	Read `integration_response`, `integration_grade`, and `branches`.
`failed`	Read `error` and handle the failure.

Start with a few seconds between polls, increase the interval for long runs, and set a maximum waiting time for your application. Match returned items to the requested agent_id values; an absent result is not evidence of completion. Output fields can be null when the automation does not provide that output.

Preserve run IDs

Persist returned run IDs before processing results. If a poll fails, retry the poll with the same IDs. Avoid automatically resending the trigger after a timeout: the original runs can still be executing, and another trigger can start additional runs. Prefer polling over wait: true, which holds the trigger connection open and can lose its response to a network timeout while execution continues.

Quickstart

Examples

Automations

Flow MCP

Endpoints

Trigger and poll automations

Start the runs

Poll by run ID

Preserve run IDs

​Start the runs

​Poll by run ID

​Preserve run IDs

Start the runs

Poll by run ID

Preserve run IDs