Executions are the result of running a workflow. The API uses an async pattern: you start an execution, then poll until it completes.

Execute a Workflow

POST /api/v1/workflows/{id}/execute

Starts a workflow execution. Returns 201 immediately with an execution ID. Use the poll endpoint to check for completion.

Request Body

Field	Type	Required	Description
nodes	Node[]	Yes	Workflow nodes with current input values
edges	Edge[]	Yes	Connections between nodes
targetNodeId	string	No	Execute only this node and its dependencies
triggerData	object	No	Data passed from an external trigger
iteratorConfigs	IteratorConfig[]	No	Iterator execution settings

Request

curl -X POST https://www.wireflow.ai/api/v1/workflows/cm1abc123/execute \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "id": "node-1",
        "type": "model",
        "position": { "x": 0, "y": 0 },
        "data": {
          "label": "Text to Image",
          "nodeType": "model:fal:text-to-image",
          "category": "model",
          "prompt": "A sunset over mountains"
        }
      }
    ],
    "edges": []
  }'

Response 201 Created

{
  "workflowId": "cm1abc123",
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "executionRuns": [
    {
      "id": "exec_456",
      "startTime": "2025-03-20T12:01:00.000Z",
      "endTime": null,
      "status": "RUNNING",
      "error": null,
      "nodeRuns": [
        {
          "nodeId": "node-1",
          "status": "COMPLETED",
          "output": {
            "images": [{ "url": "https://cdn.atomu.ai/..." }]
          }
        }
      ],
      "batchId": "550e8400-e29b-41d4-a716-446655440000",
      "runIndexInBatch": 0,
      "inputIndex": 0
    }
  ]
}

The response includes a Location header pointing to the execution status endpoint.

Insufficient Credits

If you don't have enough credits, the API returns 402:

{
  "error": "Insufficient credits. Required: 10, Available: 3",
  "insufficientCredits": true,
  "requiredCredits": 10,
  "availableCredits": 3,
  "breakdown": [
    { "nodeId": "node-1", "nodeLabel": "Text to Image", "credits": 10 }
  ]
}

Poll Execution Status

GET /api/v1/workflows/executions/{executionId}/poll

Checks the status of an async execution. For long-running AI models (video generation, etc.), poll this endpoint until status is COMPLETED or FAILED.

Request

curl https://www.wireflow.ai/api/v1/workflows/executions/exec_456/poll \
  -H "Authorization: Bearer sk-your-api-key"

Response — Running 200 OK

{
  "status": "RUNNING",
  "nodeResults": {
    "nodeRuns": [
      {
        "nodeId": "node-1",
        "status": "RUNNING",
        "output": null
      }
    ]
  }
}

Response — Completed 200 OK

{
  "status": "COMPLETED",
  "nodeResults": {
    "nodeRuns": [
      {
        "nodeId": "node-1",
        "status": "COMPLETED",
        "output": {
          "images": [{ "url": "https://cdn.atomu.ai/generated-image.png" }]
        }
      }
    ]
  }
}

Response — Failed 200 OK

{
  "status": "FAILED",
  "error": "Model inference failed",
  "nodeResults": {
    "nodeRuns": [
      {
        "nodeId": "node-1",
        "status": "FAILED",
        "error": "Provider returned 500"
      }
    ]
  }
}

Polling Strategy

We recommend polling with exponential backoff:

async function pollExecution(executionId, apiKey) {
  const baseUrl = 'https://www.wireflow.ai/api/v1';
  let delay = 1000; // Start at 1 second

  while (true) {
    const res = await fetch(
      `${baseUrl}/workflows/executions/${executionId}/poll`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const data = await res.json();

    if (data.status === 'COMPLETED') return data;
    if (data.status === 'FAILED') throw new Error(data.error);

    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10000); // Cap at 10 seconds
  }
}

Get Execution Details

GET /api/v1/workflows/executions/{executionId}

Returns the full execution record including status, node results, and metadata.

Request

curl https://www.wireflow.ai/api/v1/workflows/executions/exec_456 \
  -H "Authorization: Bearer sk-your-api-key"

Response 200 OK

{
  "id": "exec_456",
  "workflowId": "cm1abc123",
  "status": "COMPLETED",
  "triggeredBy": "manual",
  "triggerData": {},
  "nodeResults": { "nodeRuns": [...] },
  "currentNode": null,
  "output": null,
  "error": null,
  "errorNode": null,
  "executionTime": 15000,
  "creditsUsed": 10,
  "startedAt": "2025-03-20T12:01:00.000Z",
  "completedAt": "2025-03-20T12:01:15.000Z",
  "workflowSnapshot": { ... }
}

List Execution History

GET /api/v1/workflows/{id}/executions

Returns recent executions for a workflow, ordered by most recent first.

Query Parameters

Parameter	Type	Default	Description
limit	integer	10	Number of executions to return
offset	integer	0	Offset for pagination

Request

curl "https://www.wireflow.ai/api/v1/workflows/cm1abc123/executions?limit=5" \
  -H "Authorization: Bearer sk-your-api-key"

Response 200 OK

[
  {
    "id": "exec_456",
    "workflowId": "cm1abc123",
    "status": "COMPLETED",
    "triggeredBy": "manual",
    "executionTime": 15000,
    "creditsUsed": 10,
    "startedAt": "2025-03-20T12:01:00.000Z",
    "completedAt": "2025-03-20T12:01:15.000Z",
    "error": null
  }
]

Async Execution Pattern

Wireflow uses an asynchronous execution model:

1. POST to /workflows/{id}/execute — returns 201 with execution ID
2. GET to /workflows/executions/{id}/poll — returns current status
3. Repeat step 2 until status is COMPLETED or FAILED

This design handles long-running AI models (video generation can take 5+ minutes) without holding HTTP connections open.

Idempotency

Include an Idempotency-Key header to safely retry failed requests:

curl -X POST https://www.wireflow.ai/api/v1/workflows/cm1abc123/execute \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{ "nodes": [...], "edges": [...] }'

If you send the same Idempotency-Key within 24 hours, the API returns the original response instead of creating a duplicate execution.