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

# Running a workflow

> Run a workflow from New task or its own page, follow the run, decide approvals and schedule it.

You run a workflow by filling in the inputs it asks for. The run then follows the workflow's steps and stops where a person must approve. Every run you start appears in [Tasks](https://docs.neuralfactory.ai/user-guide/tasks/overview.md).

> [!NOTE]
>
> **Who:** Admins and Members (Viewers cannot run workflows) · \*\*Where:\*\***New task**, or **Workflows** › a workflow › **Runs** · **Works on:** Enterprise and SaaS

Admins and members can run every workflow they can see. A run uses the workflow's published revision, unless its owner or an admin chooses another one.

## Run from New task

**1. Pick the workflow**

On **New task**, open the worker picker at the bottom of the message box. Workflows are listed under **Workflows**, after the agents, with their published version (for example **v3 · published**). Only published workflows that are not archived are offered. Type to search, and click the star to keep a workflow at the top.

**2. Fill in the inputs**

The message box turns into the workflow's input form. Fields marked **optional** can stay empty, and some workflows group them under **Optional inputs**. Below the form, a badge says how many required inputs are still empty, or **Ready**.

* **Use last inputs** fills the form with the inputs of the workflow's last run. Files are not kept with a run, so you pick them again.
* **Fill example** fills the form with example values, where the workflow defines them.

![New task with the Expense approval workflow picked: its form with Employee, Amount and Purpose filled in, the Ready badge, and the run button.](https://mintcdn.com/neuralfactory/y-MI7aIFykaw0cY2/images/app/workflow-run-form.png?fit=max\&auto=format\&n=y-MI7aIFykaw0cY2\&q=85\&s=0b578a83fc9c3cae46252eacbb9ac9d5)

**3. Run**

Click the run button (the play icon), or press Ctrl+Enter (⌘+Enter on a Mac). The run starts on the published revision and its task page opens.

Steps that pause for a decision appear in the [Inbox](https://docs.neuralfactory.ai/user-guide/inbox.md) of the people who may decide them.

## Run from the workflow page

Open the workflow from **Workflows** (or choose **Run** in its row menu), then open the **Runs** tab.

**1. Fill in the inputs**

Under **What to run it on**, fill in the inputs. Required ones are marked with an asterisk. When the workflow has no inputs, the page says there is nothing to fill in, and you go straight to **Run**.

**2. Run**

Click **Run** in the header. If a required input is empty, the run does not start and the missing fields are listed.

**3. Follow the run**

The run's steps appear on the right as they run. While it runs, the inputs it uses stay visible, greyed out. **New run** clears them for the next run.

Beside **Current**, the **Executions** tab lists the workflow's most recent runs (**Run history**) with their status, start time, duration, cost and first inputs. Click one to show it on the right. Everyone who can open the workflow sees its runs, whoever started them.

> [accordion] Which revision Run uses
>
> * Members the workflow is shared with always run the published revision.
> * The owner and admins run the revision chosen in the header's revision picker: **Published** by default, **Draft**, or an earlier revision. **More actions** › **Test run (draft)** runs the latest saved draft. A workflow that has never been published runs its draft.

> [accordion] Why Run is disabled
>
> **Run** is disabled while the workflow has unsaved changes (**Save changes before running**), a pending proposal (**Resolve the pending proposal before running**) or issues to fix (**Fix blueprint validation issues before running**).

## Decide an approval

When a run reaches an **Approval** step, it pauses with the status **Waiting for approval**. The request appears:

* in the [Inbox](https://docs.neuralfactory.ai/user-guide/inbox.md), under **Waiting for you**, for every admin and member who can see the workflow and matches the step's approver role or groups;
* on the run page and on the workflow page's **Runs** tab;
* by email to the addresses the step lists, when your installation has email set up.

Under **Your approval is needed**, the request names the paused step. Below that come the step's prompt (when the step sets one), when it was requested and when it expires, and what happens if nobody decides in time. It also shows the main facts of the run and the content to approve.

**1. Review**

Read the request. **Technical details** shows the full data the step received.

**2. Add a comment and evidence**

**Comment** and **Evidence** (for example a ticket link or the document you reviewed) are optional. Both are recorded on the audit trail with your decision.

**3. Decide**

Click **Approve & resume run** or **Reject**. Rejecting without a comment asks you to confirm (**Reject anyway**) or to **Add a note**.

The run then continues on the approval or the rejection path that the step defines. With no rejection path set, a rejection stops the workflow. Decided requests are listed under **Decided** in the [Inbox](https://docs.neuralfactory.ai/user-guide/inbox.md).

| Rule | What it means |
| - | - |
| Four-eyes | The person who started the run cannot decide its approval, admins included. The request tells them they started this run and someone else must decide it, and they can only cancel the run. The step can lift this rule with **Allow self-approval (governance exception)**. |
| Approver role and groups | When the step names an approver role or groups, only people who match can decide. Admins match any role or group. |
| Viewers | Cannot decide approvals. |
| Timeout | When nobody decides before the request expires, the step's timeout action (approve or reject) is applied automatically. |

## The run page

A run started from **New task**, or opened from **Tasks**, has its own task page. The top shows the **Worker** (the workflow and its version), when it **Started**, its **Status**, its **Duration** and its **Cost**. When the run waited for an approval, the duration is split into time active and time waiting.

The page then shows the sections that apply to the run.

| Section | What it holds |
| - | - |
| **Input Data** | The inputs the run was given. |
| **Documents** | Files the run used (**Uploaded**) and files its steps produced (**Generated**), each downloadable. |
| **Step Execution** | Every step with its status and output. A **Live** badge shows while the run is still going. |
| **Approvals** | Each decision taken in the run, with who decided, when, their comment and evidence. |
| **Output** | What the run handed back, as **Formatted** fields or as **JSON**. |
| **Error** | Why the run failed, in plain language, with **Technical details** underneath. |
| **Audit** | The revision that ran and fingerprints of the inputs and outputs. |

| Button | What it does |
| - | - |
| **Record** | Once the run has finished, opens the run's record in [Interactions](https://docs.neuralfactory.ai/user-guide/governance/interactions.md). |
| **Audit** | Downloads the run's audit trail as a JSON file and says whether its integrity check passed. |
| **Schedule this** | Owner and admins. Schedules the workflow with these inputs. |
| **Run again** | Opens **New task** with this workflow and these inputs filled in. |
| Actions menu | **Rename**; **Stop** while the run is going or waiting; **Delete** once it has finished. Delete removes the run's steps and outputs but keeps its header, audit trail and cost. |

| Status | Meaning |
| - | - |
| **Pending** | The run is about to start. |
| **Running** | Steps are running. |
| **Waiting for approval** | The run is paused on an approval step. |
| **Completed** | Every step finished. |
| **Failed** | A step failed and its error handling stopped the run, or the run could not continue. |
| **Cancelled** | Someone cancelled the run. |
| **Timed out** | The run took longer than allowed. |

## Cancel a run

The person who started a run, or an admin, can cancel it while it is running or waiting for an approval. Click **Cancel run** next to the run (on the **Runs** tab or under a pending approval) and confirm, or choose **Stop** in the task page's actions menu.

> [!WARNING]
>
> Cancelling cannot be undone, and the run cannot be resumed. Anything its completed steps already did, such as a message sent or a record written, stays done. Cancelling a run that waits for an approval closes the request undecided.

## Schedule a workflow

The owner of a workflow and admins can run it on a schedule. Each scheduled run starts a fresh run and appears in [Tasks](https://docs.neuralfactory.ai/user-guide/tasks/overview.md).

* From **New task** or a run page: fill in the inputs, then click **Schedule** (or **Schedule this** on a run). The schedule sheet opens with those inputs. See [Schedules](https://docs.neuralfactory.ai/user-guide/tasks/schedules.md).
* From the workflow page: **More actions** › **Schedule automatic runs** opens **Schedules**. Enter a **Cron expression** (or click a preset such as **Every day at 09:00**), a **Timezone**, an optional **Name**, the **Revision** to run (**Published** or **Draft (head)**) and the **Default inputs (JSON)**, then click **Add schedule**. Each schedule shows its next and last run and its last error. Turn it off with its switch, or delete it.

An archived workflow cannot be scheduled, and its schedules do not run. On **SaaS**, your plan limits how many schedules you can have (see [Plans and limits](https://docs.neuralfactory.ai/user-guide/admin/billing.md)).

## Other ways a workflow runs

A workflow can also be started through the API with an API key (see [API keys](https://docs.neuralfactory.ai/user-guide/admin/api-keys.md) and the [API reference](https://docs.neuralfactory.ai/api-reference/introduction.md)), or by an agent that was given the workflow to run (see [Configuring agents](https://docs.neuralfactory.ai/user-guide/agents/configuring-agents.md)).

**More actions** › **Run analytics** on the workflow page counts runs by how they were started: **Manual**, **API**, **Schedule** or **Agent**.

## When a run does not start

| What you see | Why | What to do |
| - | - | - |
| Missing required inputs | A required field is empty. | Fill in the fields the form marks. |
| **Input does not match the input schema of revision r…** | The inputs do not fit the revision being run, for example after the draft's inputs changed. | Publish the draft, or test-run the draft. |
| **Workflow is archived; unarchive it to run or schedule it.** | The workflow is archived. | The owner or an admin restores it from the Workflows list. |
| **You already have … workflow runs in progress (limit …)** | Too many runs are in progress at once. | Wait for one to finish and try again. |
| A usage or budget limit message | Your plan's usage or a spend limit is used up. | See [Plans and limits](https://docs.neuralfactory.ai/user-guide/admin/billing.md), or ask an admin. |
| **This workflow isn't published yet** | You can only run its published revision, and there is none. | Ask the workflow's owner to publish it. |
| **You don't have access to this workflow** | It is not shared with you. | Ask the owner or an admin to share it. |

When a run starts but fails, open it and read **Error** on the run page. The step that failed is marked under **Step Execution**.

## Related

* [Building a workflow](https://docs.neuralfactory.ai/user-guide/workflows/building-a-workflow.md)
* [Inbox](https://docs.neuralfactory.ai/user-guide/inbox.md)
* [Schedules](https://docs.neuralfactory.ai/user-guide/tasks/schedules.md)
* [Interactions](https://docs.neuralfactory.ai/user-guide/governance/interactions.md)


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