> ## 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>

## 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 | Successfully finished |
| failed    | Encountered an error  |
| 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>

***

## 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>