> 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. 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. Search for and select the entity from which you want to run the Workflow.
3. 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>
4. Locate the Workflow you want to run, then click **Run**.\
   The **Confirm** window opens.
5. Click **Run workflow**.
6. 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.

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

**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 %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/streamline/workflows/run.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.