> ## 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 (Legacy)

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

> [!NOTE]
>
> This page documents the original routes, which keep working. For new integrations, use the `/v1` routes in [Workflows Execution](https://docs.sixtyfour.ai/api-reference/workflows/workflows-execution.md). [Legacy](https://docs.sixtyfour.ai/api-reference/legacy.md) maps each original route to its `/v1` replacement.

> [card] [API Reference](https://docs.sixtyfour.ai/api-reference/workflow/run-workflow.md)
>
> See the full request/response schema and parameters in the API Reference.

## Run workflow

Execute a workflow and receive a job ID for tracking.

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

Runs use the workflow's last valid saved definition.

| Query parameter | Required | Description |
| - | - | - |
| `workflow_id` | Yes | The workflow to run. |
| `result_formats` | No | Extra result formats to save. Accepts `csv` and `ndjson`; repeat the parameter for more than one. CSV is always saved. |
| `save_json` | No | Default `false`. Also save results as JSON, readable with `download-links?format=json`. |

> [!NOTE]
>
> To be notified when a run finishes, add an [`outgoing_webhook`](https://docs.sixtyfour.ai/api-reference/webhooks/outgoing) block to the workflow.

### Idempotency-Key header (optional)

Send an `Idempotency-Key` header to make retries safe. It is scoped to your organization and the workflow, and names one run: a repeat request with the same key, at any later time, starts no new run and returns the original `job_id` with `already_started: true` and the run's current `status`, such as `running` or `completed`. The body is not compared, so a repeat with different rows still returns the original run.

```bash theme={null}
curl -X POST "https://api.sixtyfour.ai/workflows/run?workflow_id=WORKFLOW_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: your-job-id-123" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_payload": [{ "name": "Jane Doe" }] }'
```

### Request body (optional)

| Field | Type | Description |
| - | - | - |
| `expected_revision` | integer | `edit_revision` from [Get workflow](https://docs.sixtyfour.ai/api-reference/legacy/workflows-management.md#get-workflow). The run starts only if the workflow is still at that revision and has no draft that failed validation. |
| `specs_override` | object | Overrides the first block's specs for this run. For workflows that start from an uploaded file, pass `resource_handle_id`. |
| `webhook_payload` | array or object | Input rows for workflows that start with a `webhook` block: a list of records or a single object. See [Incoming Webhooks](https://docs.sixtyfour.ai/api-reference/webhooks/incoming.md). |

> [!WARNING]
>
> Unknown body keys are ignored. If `webhook_payload` is missing or misspelled, for example `webhookPayload`, the run processes the `webhook` block's saved sample input instead of your rows, and it is billed.

### 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 workflows that start from an uploaded file, pass the `handle_id` from [Uploading an input file](https://docs.sixtyfour.ai/api-reference/legacy/workflows-overview.md#uploading-an-input-file):

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

### Response

```json theme={null}
{
  "status": "RUNNING",
  "workflow_id": "3f8b2c1e-6d4a-4f9b-8e2c-1a5b7c9d0e3f",
  "job_id": "0b9d7c1e-2f4a-4e8b-9c3d-5a6f7e8d9c0b"
}
```

`status` is uppercase `RUNNING` once the run has started. [Live status](#status-values) reports lowercase statuses. `already_started: true` is added when an `Idempotency-Key` matched an earlier request. Use `job_id` to track the run.

`status` can also be `queued`: the run is accepted but has not started yet. Track it with `job_id` as usual; repeating the request with the same `Idempotency-Key` returns this run instead of starting another.

If `webhook_payload` cannot be stored in time, the request returns `503` and starts no run; see [503 Service Unavailable](https://docs.sixtyfour.ai/api-reference/legacy/errors.md#503-service-unavailable).

> [!NOTE]
>
> To run a workflow on a recurring cadence instead of calling Run Workflow manually, see [Workflow Schedules](https://docs.sixtyfour.ai/api-reference/legacy/workflow-schedules.md).

***

## List workflow runs

Get execution history for your workflows.

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

| Query parameter | Description |
| - | - |
| `status` | Any [status value](#status-values) except `finalizing`, or `active` for queued and running runs. A finalizing run is listed as `running`. |
| `workflow_id` | Only runs of this workflow. |
| `limit` | 1 to 500, default 100. |

Runs are sorted most recent first (`queued_at` descending). Failed runs carry `error_message` and `status_reason` (`null` when no reason was recorded).

`metrics.workflow_cost_credits` is what a run cost. When you may not see what the person who started it spent, the run is still listed, `workflow_cost_credits` is `null`, and `spend_access` says why. An API key sees the costs the person who created it may see.

***

## 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 |
| finalizing | Every block has finished and the result files are being saved. Results are ready at `completed` |
| completed | Finished. Can include failed rows; see [Failed rows](#failed-rows) |
| failed | Encountered an error, or every row failed before the end of the workflow |
| cancelled | Cancelled through the API or the web app |
| terminated | Stopped by Sixtyfour before it finished |
| timeout | Stopped by a time limit |

`queued`, `running`, and `finalizing` are in progress. Every other status is final, including any status not listed here.

### Polling recommendations

* Poll every 10 seconds or slower.
* Stop when `overall_status` is anything other than `queued`, `running`, or `finalizing`.
* On `429` or `503`, wait for `Retry-After`, then poll again; see [Status polling](https://docs.sixtyfour.ai/api-reference/rate-limits.md#status-polling).
* 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 response returns `job_id`, the run's current `status`, and `cancellation_requested`.

Until the run stops, the response can show `queued` or `running` with `cancellation_requested: true`:

```json theme={null}
{
  "job_id": "0b9d7c1e-2f4a-4e8b-9c3d-5a6f7e8d9c0b",
  "status": "running",
  "cancellation_requested": true
}
```

Keep polling [live status](#get-live-status) until `overall_status` is no longer `queued`, `running`, or `finalizing`. A terminal cancellation response is:

```json theme={null}
{
  "job_id": "0b9d7c1e-2f4a-4e8b-9c3d-5a6f7e8d9c0b",
  "status": "cancelled",
  "cancellation_requested": false
}
```

> [!NOTE]
>
> If the run had already finished, the API returns its final status without changes. Results produced before cancellation stay available.

***

## Download results

Get download links for a run's result files.

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

Request links once the run's status is final. Failed and cancelled runs keep the files saved before they stopped. The response is a JSON array with one entry for each block that saved results:

* The final result file comes from the workflow's last block and is named `{run_id}.csv` (`{run_id}.json` or `{run_id}.ndjson` for those formats). It is the only file with the `Status` column described in [Failed rows](#failed-rows).
* Every other entry is one block's output, named `{run_id}_{block_number}.csv` (or `.json` or `.ndjson`).

```json theme={null}
[
  {
    "filename": "4fe6a411-ecdc-4524-9724-be968488c503_1.csv",
    "file_size": 106,
    "row_count": 2,
    "block_number": 1,
    "created_at": "2026-11-02T19:38:41.287018+00:00",
    "message": null,
    "content_type": "text/csv",
    "download_url": "https://api.sixtyfour.ai/storage/download/v1.eyJlIjoxNzkzNjQ5...",
    "download_expires_in_seconds": 900,
    "results": [
      {
        "email": "jane@northgatelabs.com",
        "phone": "+14155550123"
      },
      {
        "email": "sam@pacificviewstudios.com",
        "phone": "+12065550188"
      }
    ]
  },
  {
    "filename": "4fe6a411-ecdc-4524-9724-be968488c503.csv",
    "file_size": 320,
    "row_count": 2,
    "block_number": 2,
    "created_at": "2026-11-02T19:38:48.624741+00:00",
    "message": null,
    "content_type": "text/csv",
    "download_url": "https://api.sixtyfour.ai/storage/download/v1.eyJlIjoxNzkzNjQ5...",
    "download_expires_in_seconds": 900,
    "results": [
      {
        "email": "jane@northgatelabs.com",
        "phone": "+14155550123",
        "email_state": "deliverable"
      },
      {
        "email": "sam@pacificviewstudios.com",
        "phone": "+12065550188",
        "email_state": "undeliverable"
      }
    ]
  }
]
```

| Field | Description |
| - | - |
| `filename` | `{run_id}.csv` for the final file, `{run_id}_{block_number}.csv` for one block's output |
| `block_number` | Sequence number of the block that wrote the file |
| `row_count` | Rows in the file |
| `file_size` | Size in bytes, or `null` |
| `content_type` | `text/csv`, `application/json`, or `application/x-ndjson` |
| `download_url` | The file's download link, or `null` when no link could be created |
| `download_expires_in_seconds` | Seconds until `download_url` expires: `900` |
| `results` | The file's rows inline when it has at most 200 rows and 512 KB, otherwise `null`. CSV values are the stored cell text and are never spreadsheet-escaped |
| `message` | A note about the file, such as that it is still being saved, or `null` |

Every result file starts with a `_row_id` column that numbers its rows from `1`.

Pass `format=csv` (default), `format=json`, or `format=ndjson`. JSON links exist only for runs started with `save_json=true`, and NDJSON links only for runs started with `result_formats=ndjson`.

In workflow, search and Atlas CSV exports, list and object cells contain JSON; booleans are `true` or `false`. Parse list and object cells with `json.loads()` or `JSON.parse()`. Python's `ast.literal_eval()` does not accept JSON `null`, `true` or `false`. Previously saved files keep their original text.

Each `download_url` needs an `x-api-key` header from the run's organization. Reuse it until it expires instead of requesting new links.

While a step's result files are still being saved, its CSV entry carries a `message` saying so, and its `download_url` and inline `results` already serve its rows. JSON and NDJSON link requests return `503` with a `Retry-After` header until the files are saved; see [workflow result download retries](https://docs.sixtyfour.ai/api-reference/legacy/errors.md#workflow-result-download-retries). A run with a large result file can also finish later than usual while that file saves. Do not rerun the workflow.

Link requests and file downloads each have an organization-wide budget; see [Rate limits](https://docs.sixtyfour.ai/api-reference/rate-limits.md#workflows). For rate-limit responses and retry timing, see [workflow result download retries](https://docs.sixtyfour.ai/api-reference/legacy/errors.md#workflow-result-download-retries).

### Spreadsheet-safe CSV

CSV downloads are escaped for spreadsheets by default. A cell that starts with `=`, `+`, `-`, `@`, a tab, or a line break gets a leading `'`, so a spreadsheet shows it as text instead of running it as a formula. For example, `+14155550123` downloads as `'+14155550123` and `@northgate` as `'@northgate`. Negative numbers such as `-12.5` are unchanged. Every field is quoted, and the response carries an `X-Spreadsheet-Safe: 1` header.

To get the file exactly as stored, add `?spreadsheet_safe=false` to the `download_url`. JSON and NDJSON files are never escaped. When code reads the results, request NDJSON with `result_formats=ndjson`.

```bash theme={null}
curl "DOWNLOAD_URL?spreadsheet_safe=false" \
  -H "x-api-key: YOUR_API_KEY" \
  -o results.csv
```

***

## 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
* carries a `_block_failed` column in result files, set to the `block_name` of the step it failed at, such as `lead_enrichment`
* 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

```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"]

IN_PROGRESS = {"queued", "running", "finalizing"}
while True:
    status_response = requests.get(
        f"{BASE_URL}/workflows/runs/{job_id}/live_status",
        headers=headers
    )
    if status_response.status_code in (429, 503):
        time.sleep(int(status_response.headers.get("Retry-After", 10)))
        continue
    status_response.raise_for_status()
    status = status_response.json()
    if status["overall_status"] not in IN_PROGRESS:
        break
    time.sleep(10)

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();

const IN_PROGRESS = ["queued", "running", "finalizing"];
let status;
while (true) {
  const statusResponse = await fetch(
    `${BASE_URL}/workflows/runs/${job_id}/live_status`,
    { headers }
  );
  if (statusResponse.status === 429 || statusResponse.status === 503) {
    const retryAfter = Number(statusResponse.headers.get("Retry-After") ?? 10);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    continue;
  }
  if (!statusResponse.ok) throw new Error(`Live status failed: ${statusResponse.status}`);
  status = await statusResponse.json();
  if (!IN_PROGRESS.includes(status.overall_status)) {
    break;
  }
  await new Promise((r) => setTimeout(r, 10000));
}

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}`));
}
```

## Pricing

See [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md) for more information.

## Related

* [Workflow Blocks](https://docs.sixtyfour.ai/api-reference/workflows/workflow-blocks.md)
* [Workflow Schedules](https://docs.sixtyfour.ai/api-reference/legacy/workflow-schedules.md)
* [Handling Errors](https://docs.sixtyfour.ai/api-reference/legacy/errors.md)


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