List Queued RunsCopy Anchor Link

GET /api/runs/queue?filter[organizationId]=org_123&filter[actionFlowId]=flow_123&page[number]=1&page[size]=20

The endpoint is an active-queue view for the authorized organization. By default it returns only waiting and dispatching items; it does not expose dispatched, failed, or cancelled items. It is separate from run history and from the execution service's run status. Use Get Queued Run to observe one queue item after it leaves this active view.

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

Send a request to see the response.

AuthenticationCopy Anchor Link

Required. External queue integrations should use an API key. The same route also accepts an authenticated application session, such as a valid signed-in app session cookie. An organization-scoped API key supplies its key organization, so the organization filter is optional. A user-scoped API key has no activeOrganizationId and must provide filter[organizationId] for an organization the user can access. An application session may use its active or requested organization and checks the session user's permission.

Query parametersCopy Anchor Link

The current queue list has no filter[status] parameter. Use the returned item status to distinguish waiting from dispatching, and use Queued Run for one item.

ResponseCopy Anchor Link

The top-level data value is an object, not an array. In short, the response shape is data: { items, total }:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "queue_123",
        "actionFlowId": "flow_123",
        "organizationId": "org_123",
        "status": "waiting",
        "position": 1,
        "triggerRunId": null,
        "error": null,
        "createdAt": "2026-09-24T10:00:00.000Z",
        "updatedAt": null,
        "dispatchedAt": null
      }
    ],
    "total": 1
  }
}

Each item exposes the queue ID, organization and ActionFlow IDs, queue status, position, runtime run ID when available, error text, and timestamps. total is the number of matching active items before page truncation. position is a one-based position among waiting items represented on the current page, or null for a non-waiting item.

Polling and handoffCopy Anchor Link

When POST /api/runs returns 202, save its queueId and runHistoryId. Use queueId with Get Queued Run as the authoritative status endpoint. This list is only for active waiting and dispatching items; a dispatched, failed, or cancelled item will no longer appear here. Poll the detail endpoint until it reports one of those states and retrieve triggerRunId when present from the detail response. A waiting item can be cancelled with DELETE /api/runs/queue/{queueId}; see Queued Run.

A queue item is admission state, not proof that graph execution completed. Queue-time validation and later node execution can still fail after the item is dispatched.

RelatedCopy Anchor Link

• Trigger Run
• Queued Run
• Get Run
• TypeScript SDK runs
• Flow troubleshooting