> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/streamline/workflows/run.md).

# Running a Workflow

After you've [created a Workflow](/streamline/workflows/create.md), [configured its basic settings](/streamline/workflows/configuring-workflow-settings.md), and [added blocks](/streamline/workflows/blocks.md), you're ready to run it.

You can run a Workflow in the following ways:

* [Directly after configuration](#running-a-workflow-directly-after-configuration)
* [From the Workflows page](#running-a-workflow-from-the-workflows-page-via-the-main-sidebar) (via the main sidebar)
* [From an entity](#running-a-workflow-from-an-entity)
* [Via the API](#running-a-workflow-via-the-api)

{% hint style="info" %}
To run a Workflow with Cortex-based blocks, you need the appropriate [permissions](/configure/settings/managing-users/permissioning.md) for each block. For example, a block that adds Eng Intelligence custom metrics to an entity requires the `Configure Eng Intelligence Custom Metrics` permission to run successfully.
{% endhint %}

## Prerequisites

1. You must have the `Execute Workflows Runs` permission.
2. An existing Workflow. If you haven't yet created a Workflow, refer to [Creating a Workflow](/streamline/workflows/create.md), [Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings.md), and [Adding blocks to a Workflow](/streamline/workflows/blocks.md).

## Running a Workflow directly after configuration

1. In the upper-right corner of the page, click **Run**.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/xJv5lhZjcgcefeTuMPZE" alt="The &#x27;Run&#x27; icon in the upper-right corner of the Workflow page." width="375"><figcaption></figcaption></figure></div>
2. Click **Run workflow**.

## Running a Workflow from the Workflows page (via the main sidebar)

1. From the main sidebar, select **Workflows**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's Workflows.
   * Select the **Mine** tab to search and filter only the Workflows you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow you want to run, then click **Run**. Note that if the Workflow is scoped to an entity, the **Select an entity** window opens. Select an entity from the drop-down menu, then click **Run workflow**.

{% hint style="info" %}
Workflows that require user input or manual approval pause until the configured input or approval is completed.
{% endhint %}

Nested form inputs configured with **Data type: String** render as a simple list of text fields, one per row, with an **Add** button and a **Remove** button (trash icon). **Data type: Object** nested forms render the configured sub‑form per row.

<div align="left" data-with-frame="true"><figure><img src="/files/nBfqBmBI2hbJLrPrSBDg" alt="Nested form String input at runtime: one text field per row with Add and remove buttons." width="375"><figcaption></figcaption></figure></div>

## Running a Workflow from an entity

Follow the steps below to run a Workflow from an entity.

{% hint style="info" %}
Workflows are linked to entities only if specified during configuration. To link an existing Workflow to an entity, edit the Workflow first.
{% endhint %}

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Search for and select the entity from which you want to run the Workflow.
4. From the entity details sidebar, select **Workflows**.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/juIPnnAuJNBB2ZvPlW1J" alt="" width="375"><figcaption></figcaption></figure></div>
5. Locate the Workflow you want to run, then click **Run**.\
   The **Confirm** window opens.
6. Click **Run workflow**.
7. Click the tile to view the recent run.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/TUEZQnycqHhhahaatEvw" alt="The run tile." width="375"><figcaption></figcaption></figure></div>

## Running a Workflow via the API

You can trigger Workflows programmatically using the [Workflow Runs API](/api/readme/workflows.md). This is useful for integrating Cortex Workflows into CI/CD pipelines, scripts, and other automation.

**Prerequisites**

1. The Workflow must have **Runnable via API** enabled. See [Enabling API access](/streamline/workflows/publishing-a-workflow.md#enabling-api-access).
2. The caller must authenticate with a [personal access token](/configure/settings/api-keys/personal-tokens.md) or a [global API key](/configure/settings/api-keys.md) that has the `Execute Workflow Runs` permission.

**What you can do via the API**

* Trigger a Workflow run for a global or entity‑scoped Workflow.
* Pass runtime values into Workflow variables using `initialContext`. See step 1-i in [Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings.md#configuring-workflow-settings).
* Specify the initiating user with `runAs` —required when the Workflow restricts inputs to the initiator, when authenticating with a workspace or global API key, or when the Workflow contains a Scaffolder block. If `runAs` is omitted and an initiator is required, the run pauses and prompts for user selection.
* Notify additional users of run events with `notificationRecipients`.
* Prevent duplicate runs from accidental retries by sending an `Idempotency-Key` header.
* Retrieve a specific run or list runs with filters.

For full request and response details, see the [Workflow Runs API](/api/readme/workflows.md) reference.

API‑initiated runs appear on the **Runs** tab alongside UI runs. See [Tracking API‑initiated runs](/streamline/workflows/viewing-workflows.md#tracking-api-initiated-runs).

## **Running a Workflow with secret user input**

When a Workflow includes a secret user input block, Cortex prompts the user to enter a value and redacts it in the **Outputs** tab. If the block has regex validation configured, the user's input must match the Validation regex set for that block.

The **Outputs** tab shows the secret fields after the Workflow runs, but Cortex redacts the values themselves.

{% hint style="warning" %}
It's possible for users with the `Edit Workflows` permission to obtain secret values using complex data transformation on secrets or echoing services.
{% endhint %}

## Running a Workflow with list inputs

When a user input collects a list (nested form with the single value data type), the runner can add or remove entries within the configured element count. Number items are validated against the Integer/Decimal format and any minimum or maximum you set, and toggle items are entered as true/false switches.

## Viewing a Workflow run

See the documentation for [viewing a Workflow run](/streamline/workflows/viewing-workflows.md).

## Canceling a run

Follow the steps below to cancel a run.

{% hint style="info" %}
Canceling a partially complete run does not impact any blocks that have been successfully completed.
{% endhint %}

1. On the Workflows page, select the **Runs** tab.
2. Select the run you want to cancel.
3. In the upper-right corner of the page, click **Cancel run**. The run is terminated.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/xqx8u7Ja7ar7GLeYsyPR" alt="" width="563"><figcaption></figcaption></figure></div>

[Next step: Publishing a Workflow](/streamline/workflows/publishing-a-workflow.md)

## Troubleshooting and FAQ

**When trying to run a Workflow, why might I get the 404 error** `could not find workflow with id: xyz`**?**

This happens when you have multiple tenants and use an API key from the wrong tenant. Ensure that you are using the correct API key, or create a new API key and try again.

**Why do I see a** `403 Forbidden IP address` **error when running a Workflow?**

Workflow steps that call the Cortex API fail if the request originates from an IP that isn't on your allowlist. Send a message to <help@cortex.io> if you need further assistance.