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

# Run a workflow via API

> Start, inspect, cancel, or wake a published event-to-call workflow.

Open a published [workflow](/deploy/workflows) and expand **Run via API**. The panel shows the endpoint for that workflow.

Requests are rejected until the workflow is **Live**.

## How to connect

<Steps>
  <Step title="Create an API key">
    Create an API key for this workspace with the `workflow run` scope. Add `workflow read` to check status. See [API keys](/accounts/api-keys).
  </Step>

  <Step title="Send headers">
    Send the key in the `X-API-Key` header, with a unique `Idempotency-Key` per run.
  </Step>

  <Step title="Pass context">
    Put input in `context`. For example `phone_number` becomes `{{phone_number}}` in later steps.
  </Step>
</Steps>

Runs start in parallel. Add a `Concurrency-Key` (for example a store id) to allow only one active run per key; others return 409.

Optional `Cooldown-Minutes` (0–10080) refuses a new run for that key until this many minutes after its last run ended.

## Start a run

`POST https://api.persistence.dev/v1/workflows/{workflowId}/run`

```bash theme={null}
curl -X POST https://api.persistence.dev/v1/workflows/{workflowId}/run \
  -H "X-API-Key: <your-api-key>" \
  -H "Idempotency-Key: <unique-request-id>" \
  -H "Concurrency-Key: <optional, e.g. store-10>" \
  -H "Content-Type: application/json" \
  -d '{"context": {"phone_number": "+14155550123"}}'
```

A successful start returns `202` with a `runId` in `data.id`.

## Check status

`GET https://api.persistence.dev/v1/workflows/{workflowId}/runs/{runId}`

```bash theme={null}
curl https://api.persistence.dev/v1/workflows/{workflowId}/runs/{runId} \
  -H "X-API-Key: <your-api-key>"
```

Requires the `workflow read` scope. Status values match the **Runs** tab: `queued`, `running`, `waiting_call`, `waiting_schedule`, `waiting_automation`, `blocked`, `completed`, `failed`, `cancelled`.

## Cancel

Cancel one run:

`POST /v1/workflows/{workflowId}/runs/{runId}/cancel`

Cancel every active run, or only those that share concurrency keys:

`POST /v1/workflows/{workflowId}/runs/cancel`

```bash theme={null}
curl -X POST https://api.persistence.dev/v1/workflows/{workflowId}/runs/cancel \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'
```

Or send `"concurrencyKeys": ["store-10"]` instead of `"all": true`. You can include an optional `reason`. Workflows with **Send the failure webhook when a run is cancelled** notify that webhook for each cancelled run.

## Wake a waiting run

If a run is sleeping at a **Delay** (or another wait step) for a promised time, you can continue it now. Runs pausing between call retries are not woken.

`POST /v1/workflows/{workflowId}/runs/wake`

```bash theme={null}
curl -X POST https://api.persistence.dev/v1/workflows/{workflowId}/runs/wake \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"concurrencyKeys": ["store-10"]}'
```

Send 1–500 concurrency keys. The response lists the run ids that woke.

<Card title="Workflows API" icon="code" href="/api-reference/workflows/overview">
  Request and response contracts for start, status, cancel, and wake.
</Card>


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