Runs
Start an ActionFlow run, poll or stream status, list history, cancel work, and inspect the organization run queue with the TypeScript SDK.
Runs
Start and observe ActionFlow executions. runActionFlow is asynchronous: it returns a run id (or queue info) while the graph runs in the background.
import { ActionFlows } from "actionflows";
const client = new ActionFlows({
apiKey: process.env.ACTIONFLOWS_API_KEY!,
});See Installation for install and auth. Discover flow ids with ActionFlows.
Start a run
import type { RunActionFlowOptions } from "actionflows";
const options: RunActionFlowOptions = {
idempotencyKey: `run-${Date.now()}`,
tags: ["production", "api"],
maxAttempts: 3,
inputs: {
// Actionflow Studio Flow inputs keys: {nodeId}_{inputName}
},
trigger: {
body: { hello: "world" },
method: "POST",
},
};
const run = await client.runActionFlow("org_123", "flow_456", options);
console.log("Started run:", run.id);When the organization run queue is enabled, the response can be a queued item (queueId) instead of an immediate run id. See Trigger Run.
| Option | Type | Description |
|---|---|---|
idempotencyKey | string | Repeated key returns the existing run |
delay | string | Delay before start (30s, 5m, 1h, 2d) |
tags | string[] | Tags for filtering later |
maxAttempts | number | Retry attempts on failure |
maxDuration | number | Max duration in seconds |
userId | string | User to associate with the run |
inputs | Record<string, unknown> | Per-run overrides, same keys as Studio Flow inputs |
trigger | object | Optional envelope on the start node (body, headers, query, method) |
inputs and trigger are optional. Webhook and scheduled starts still supply their own envelopes.
There is no SDK upload method. Put files in the app (ActionFlow artifacts), or pass values the flow already expects in inputs.
The flow is validated before it runs. Validation errors throw (see Trigger Run).
Get a run
runActionFlow returns only the id when the run is dispatched immediately. Poll getRun for status, per-node outputs, cost, and timing.
const result = await client.getRun(run.id);REST: Get Run.
List runs
const flowRuns = await client.getActionFlowRunHistory("flow_456", {
status: ["COMPLETED"],
pageSize: 20,
});
const allRuns = await client.listRuns({
organizationId: "org_123",
pageSize: 50,
});| Param | Type | Description |
|---|---|---|
pageSize | number | Page size |
pageAfter / pageBefore | string | Cursors |
status | string[] | Filter by status |
tag | string[] | Filter by tags |
organizationId | string | Organization filter (listRuns) |
isTest | boolean | Test runs |
createdAtFrom / createdAtTo / createdAtPeriod | string | Time filters |
REST: List Runs, List Flow Runs.
Cancel or stream
await client.cancelRun(run.id);
const response = await client.streamRun(run.id);
// Raw SSE Response for GET /api/runs/{runId}/streamREST: Cancel Run, Stream Run.
Run queue
When the org queue is on:
const queued = await client.listQueuedRuns("org_123");
const item = await client.getQueuedRun("queue_item_id", "org_123");
await client.cancelQueuedRun("queue_item_id", "org_123");REST: List Queued Runs, Queued Run.