> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sixtyfour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Execution

> Run workflows, poll status, cancel runs, and download results.

## Use case

Execute batch enrichment pipelines, monitor progress in real time, and retrieve results. Use these endpoints to run workflows with input data, poll for completion, cancel long-running runs, and download enriched output files.

<Card title="API Reference" icon="code" href="/api-reference/workflow/run-workflow">
  See the full request/response schema and parameters in the API Reference.
</Card>

## Pricing

See [Credits & Pricing Guide](/guides/credits-and-pricing) for credit costs.

## Errors

For error responses (400, 403, 404, 409, etc.), see [Handling Errors](/api-reference/errors).

***

## Run workflow

Execute a workflow and receive a job ID for tracking.

```http theme={null}
POST https://api.sixtyfour.ai/workflows/run
```

Pass `workflow_id` as a query parameter. The optional request body accepts `specs_override` (to override the first block's specs for dynamic inputs) and `webhook_payload` (input data for workflows starting with a `webhook` block).

| Name | Required | Description |
| - | - | - |
| workflow\_id | Yes | The workflow to execute |

### Request Body (Optional)

| Field | Type | Description |
| - | - | - |
| specs\_override | object | Override specs of the first block for this run. For workflows starting with `read_csv`, pass `specs_override.resource_handle_id` from `/storage/csv/upload`. |
| webhook\_payload | array or object | Input data for workflows starting with a webhook block. API key auth only. Can be a list of records or a single object. See [Incoming Webhooks](/api-reference/webhooks/incoming) for the full spec. |

### Example Request

```json theme={null}
{
  "webhook_payload": [
    {
      "company_name": "Acme Corp",
      "website": "acme.com",
      "industry": "Technology"
    },
    {
      "company_name": "TechStart Inc",
      "website": "techstart.io",
      "industry": "Software"
    }
  ]
}
```

For `read_csv` workflows, use the `handle_id` returned by `/storage/csv/upload`:

```json theme={null}
{
  "specs_override": {
    "resource_handle_id": "22222222-2222-2222-2222-222222222222"
  }
}
```

<Tip>Use the `job_id` returned in the response to track workflow execution. Check the workflow editor's "Workflow API Reference" for specific `specs_override` options.</Tip>

<Note>To run a workflow on a recurring cadence instead of calling Run Workflow manually, see [Workflow Schedules](/api-reference/workflows/workflow-schedules).</Note>

***

## List workflow runs

Get execution history for your workflows.

```http theme={null}
GET https://api.sixtyfour.ai/workflows/runs
```

Optional query parameters: `status` (`running`, `completed`, `cancelled`, or `active`), `workflow_id`, and `limit` (1–500, default 100). Results are sorted by most recent first (`queued_at` descending). For failed runs, `error_message` and `status_reason` may be populated.

***

## Get live status

Monitor real-time progress of a running workflow.

```http theme={null}
GET https://api.sixtyfour.ai/workflows/runs/{run_id}/live_status
```

`run_id` is the same as the `job_id` returned by Run Workflow.

### Status values

| Status | Description |
| - | - |
| queued | Waiting to start |
| running | Currently executing |
| completed | Finished. Some rows may still have failed; see [Failed rows](#failed-rows) |
| failed | Encountered an error, or every row failed before the end of the workflow |
| cancelled | Manually cancelled |

### Polling recommendations

* Poll every 5–10 seconds for running workflows
* Stop polling when `overall_status` is `completed`, `failed`, or `cancelled`
* Use `overall_progress_percentage` for progress bars

***

## Cancel run

Stop an in-progress workflow execution.

```http theme={null}
POST https://api.sixtyfour.ai/workflows/cancel
```

Pass `job_id` (from the Run Workflow response) as a query parameter. The request body is optional — send an empty object `{}` or omit.

<Note>If the run has already completed, failed, or been cancelled, the API returns the current status without changes. Partial results may be available.</Note>

***

## Download results

Get signed download URLs for workflow results.

```http theme={null}
GET https://api.sixtyfour.ai/workflows/runs/{run_id}/results/download-links
```

Returns one entry per result file. Each block may produce separate files; results are typically in CSV format.

<Warning>Signed URLs expire after 15 minutes (900 seconds). Download files immediately or request new links.</Warning>

***

## Failed rows

A row fails at a step when that step still cannot process it after its retries. A failed row:

* skips every later step and is not charged for those steps
* stays in the output, with `Failed` in the columns the failing step would have filled
* is still sent to an outgoing webhook step

The final result file ends with a `Status` column set to `Succeeded` or `Failed` for each row. If your data already has a column named `Status`, it is kept as is and the added column is named `Workflow status`. If that name is also taken, the added column uses the first available numbered name, starting with `Workflow status 2`.

A run with some failed rows finishes as `completed`. It finishes as `failed` only when no row made it through the workflow. List workflow runs returns the counts in each run's `metrics`:

| Field | Description |
| - | - |
| `failed_row_count` | Total rows that failed, across all steps |
| `failed_rows` | Per step: `block_id`, `block_name`, `sequence_number`, and `count` of rows that failed at that step |
| `failed_steps` | Block IDs of steps that every row had already failed before reaching |

These fields are omitted when no row failed.

***

## Example usage

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time

  API_KEY = "YOUR_API_KEY"
  WORKFLOW_ID = "YOUR_WORKFLOW_ID"
  BASE_URL = "https://api.sixtyfour.ai"
  headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

  run_response = requests.post(
      f"{BASE_URL}/workflows/run?workflow_id={WORKFLOW_ID}",
      headers=headers,
      json={
          "webhook_payload": [
              {"company_name": "Acme Corp", "website": "acme.com"},
              {"company_name": "TechStart", "website": "techstart.io"}
          ]
      }
  )
  run_response.raise_for_status()
  job_id = run_response.json()["job_id"]

  while True:
      status = requests.get(
          f"{BASE_URL}/workflows/runs/{job_id}/live_status",
          headers=headers
      ).json()
      if status["overall_status"] in ["completed", "failed", "cancelled"]:
          break
      time.sleep(5)

  if status["overall_status"] == "completed":
      links = requests.get(
          f"{BASE_URL}/workflows/runs/{job_id}/results/download-links",
          headers=headers
      ).json()
      for r in links:
          print(f"{r['filename']}: {r['download_url']}")
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = "YOUR_API_KEY";
  const WORKFLOW_ID = "YOUR_WORKFLOW_ID";
  const BASE_URL = "https://api.sixtyfour.ai";
  const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };

  const runResponse = await fetch(
    `${BASE_URL}/workflows/run?workflow_id=${WORKFLOW_ID}`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        webhook_payload: [
          { company_name: "Acme Corp", website: "acme.com" },
          { company_name: "TechStart", website: "techstart.io" }
        ]
      })
    }
  );
  if (!runResponse.ok) {
    const err = await runResponse.json();
    throw new Error(`Failed to start workflow: ${JSON.stringify(err)}`);
  }
  const { job_id } = await runResponse.json();

  let status;
  while (true) {
    const statusResponse = await fetch(
      `${BASE_URL}/workflows/runs/${job_id}/live_status`,
      { headers }
    );
    status = await statusResponse.json();
    if (["completed", "failed", "cancelled"].includes(status.overall_status)) {
      break;
    }
    await new Promise((r) => setTimeout(r, 5000));
  }

  if (status.overall_status === "completed") {
    const linksResponse = await fetch(
      `${BASE_URL}/workflows/runs/${job_id}/results/download-links`,
      { headers }
    );
    const links = await linksResponse.json();
    links.forEach((r) => console.log(`${r.filename}: ${r.download_url}`));
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.