# Workflow Runs API

We invite you to try our expanded Cortex Workflows public API. The new Workflow Runs API lets you trigger, monitor, and list workflow runs programmatically, so you can integrate Cortex Workflows into your existing CI/CD pipelines, scripts, and automation tools.

## What's new

Trigger workflow runs via API and track their execution without leaving your terminal or toolchain.

* Trigger a workflow run for global or entity-scoped workflows
* Get details of a specific workflow run
* List workflow runs with filtering by workflow, entity, initiator, and date range
* Pass initial context variables to customize workflow behavior at runtime
* Chain workflows together using the new Run Workflow action block

## Prerequisites

1. In Cortex, enable API access for each workflow you want to trigger:
   1. From the main sidebar, select **Workflows**.
   2. Locate the workflow, then click the **Overflow** **icon**.
   3. Select **Edit workflow**.
   4. In the upper-right corner, click **Access**.<br>

      <div align="left" data-with-frame="true"><figure><img src="/files/jjsdoO4fXbNceggMGXyQ" alt="The &#x27;Access&#x27; button in the upper-right corner of the page." width="375"><figcaption></figcaption></figure></div>
   5. Toggle on **Runnable via API**, then click **Apply**.<br>

      <div align="left" data-with-frame="true"><figure><img src="/files/tKsHAZBKfNIj2zuQW6Vf" alt="Th &#x27;Runnable via API&#x27; option is toggled on." width="375"><figcaption></figcaption></figure></div>
   6. Repeat these steps for each workflow you want to trigger.
2. Use either a [personal access token](/configure/settings/api-keys/personal-tokens.md) or a [global API key](/configure/settings/api-keys.md) with the `Execute Workflow Runs` permission.

## Using the Workflow Runs API

{% hint style="info" %}
A maximum of 5 workflows may run concurrently. Paused workflows are excluded from this limit.
{% endhint %}

### Triggering a workflow run

`POST /api/v1/workflows/{workflowTagOrId}/runs`

Start a new workflow run. Note that the workflow must have the [Runnable via API option](#prerequisites) enabled.

**Parameters**

<table><thead><tr><th width="246.14453125">Parameter</th><th width="109.64453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>scope</code></td><td>Yes</td><td>Object specifying run scope. Use <code>{"type": "GLOBAL"}</code> for global workflows, or <code>{"type": "ENTITY", "entityId": "&#x3C;entity-id>"}</code> for entity-scoped workflows.</td></tr><tr><td><code>notificationRecipients</code></td><td>No</td><td>List of user emails to notify for workflow events (e.g., when the workflow pauses for input).</td></tr><tr><td><code>runAs</code></td><td>No</td><td>Email of the user to act as the initiator. See "A note on runAs" below.</td></tr><tr><td><code>initialContext</code></td><td>No</td><td>Key-value pairs matching workflow variable slugs. See "Passing initial context" below.</td></tr><tr><td><code>Idempotency-Key</code> (header)</td><td>No</td><td>Unique string to prevent duplicate runs from accidental retries. Subsequent calls with the same key return the cached result.</td></tr></tbody></table>

**Example request**

```
POST /api/v1/workflows/my-deployment-workflow/runs
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "scope": {
    "type": "ENTITY",
    "entityId": "service-frontend"
  },
  "runAs": "deployer@example.com",
  "notificationRecipients": [
    "team-leads@example.com",
    "devops@example.com"
  ],
  "initialContext": {
    "environment": "staging"
  }
}
```

### Retrieving the details of a workflow run

`GET /api/v1/workflows/{workflowTagOrId}/runs/{runId}`

Retrieve the current status and details of a specific workflow run.

**Example request**

```
GET /api/v1/workflows/my-deployment-workflow/runs/run-12345
Authorization: Bearer YOUR_API_KEY
```

### Listing workflow runs

`GET /api/v1/workflows/runs`

Retrieve a list of workflow runs with optional filters.

**Filters**

<table><thead><tr><th width="192.81640625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>workflowIds</code></td><td>List of workflow identifiers to filter by</td></tr><tr><td><code>searchQuery</code></td><td>Search by workflow name or description</td></tr><tr><td><code>entityId</code> or <code>Tag</code></td><td>Filter by the entity the workflow was run against</td></tr><tr><td><code>initiatedBy</code></td><td>Filter by the email of the user who initiated the run</td></tr><tr><td><code>startedAfter</code></td><td>Return only runs started after this date</td></tr><tr><td><code>startedBefore</code></td><td>Return only runs started before this date</td></tr></tbody></table>

**Example request**

```
GET /api/v1/workflows/runs?workflowIds=deployment-pipeline
Authorization: Bearer YOUR_API_KEY
```

### Passing initial context

You can pass context variables to a workflow at runtime to customize its behavior. Set up variables in your workflow first:

1. From the main sidebar, select **Workflows**.
2. Locate the workflow, then click the **Overflow** **icon**.
3. Select **Edit workflow**.
4. In the right pane, scroll to the **Variables** section, then click **Add variable**.
5. Reference the variable in subsequent blocks using overrides or parameters.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/5gxnYSFS9yYdD7aQuFrr" alt="The &#x27;Variables&#x27; section in the right pane within a workflow." width="375"><figcaption></figcaption></figure></div>
6. Click **Add**, then click **Save**.

When triggering a run via the API, pass values in the `initialContext` field. Each key must match a variable slug defined in the workflow.

### A note on runAs

The `runAs` parameter specifies which user the workflow should treat as the initiator. Use this when:

* The workflow has inputs restricted to the initiator only and you're using a workspace or global API key
* The workflow includes a Scaffolder block, which requires a user for steps like setting an owner

If no `runAs` is provided and the workflow requires an initiator, the workflow will pause and prompt for user selection.

Workflows can be tracked in the **Runs** tab and the `runAs` can be found in the Run context.

## Using the Run Workflow action block

You can now chain workflows together using the Run Workflow block in the workflow editor.

{% hint style="info" %}
The embedded workflow and the parent workflow have a strict parent-child relationship to prevent accidental workflow looping.
{% endhint %}

**To use the Run Workflow action block**:

1. From the main sidebar, select **Workflows**.
2. Locate the workflow, then click the **Overflow** **icon**.
3. Select **Edit workflow**.
4. Click the **+ icon** at the bottom of the workflow.
5. Search for and select the **Run workflow** block.
6. In the right pane, do the following:
   1. Under **Block** **name**, enter a name for the block.
   2. Optionally, change the slug. The slug auto-populates based on the block name.
   3. From the **Workflow** drop-down menu, select the workflow to run.
   4. Optionally, from the **Entity** drop-down menu, specify an entity to run the target workflow against. If the target workflow is entity-scoped and no entity is provided, it pauses for input.
7. Click **Save**.

<div align="left" data-with-frame="true"><figure><img src="/files/Z2Sq15sihf56mZxhKmFb" alt="A workflow as displayed in the Cortex UI with the &#x27;Run workflow&#x27; block." width="375"><figcaption></figcaption></figure></div>

## Tracking API-initiated runs

On the **Workflows > Runs** page in the Cortex UI, runs triggered via the API are marked with a key icon.

<div align="left" data-with-frame="true"><figure><img src="/files/oSpzfZM3CgnIKOVpg2Ff" alt="The key icon is displayed next to the individual&#x27;s name who ran the workflow." width="563"><figcaption></figcaption></figure></div>

Runs that failed to initiate via the API appear in the **Failures** tab. To view more information about a failed run, click **View details**.

<div align="left" data-with-frame="true"><figure><img src="/files/UQ4nYEDvKCVySQQDvMlZ" alt="The &#x27;Failures&#x27; tab on the Workflows page in the Cortex UI." width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
The **Failures** tab only appears if there are failed runs.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/resources/beta/workflow-runs-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.