> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/workflow/workflow-execution.md).

# Run a workflow

This article explains how to run workflows, use preview runs, and configure triggers.

## Execution triggers

You can start a workflow in the following four ways.

| Trigger           | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| Manual run        | Start the workflow immediately from the UI                  |
| API trigger       | Start the workflow from an external system via HTTP request |
| Scheduled trigger | Start the workflow automatically on a recurring schedule    |
| GitHub Webhook    | Start the workflow automatically based on GitHub events     |

{% hint style="warning" %}
By default, the same workflow can run multiple executions concurrently. In the trigger settings for **API access**, **Schedule**, and **GitHub webhooks**, you can change the concurrency behavior to **Run in parallel** or **Cancel previous executions**. If your organization reaches its workflow concurrency limit, additional runs enter **Queued** and start automatically when a slot frees up.
{% endhint %}

## Manual run

You can start a workflow manually from either the list screen or the editor screen.

**Run from the list screen**

In the action menu of each row of the workflow list, click **Run** (the play icon).

{% hint style="info" %}
If the workflow has no user inputs configured, a confirmation screen appears so you can enter inputs and run the workflow directly.
{% endhint %}

## Preview run

A preview run is recorded in the run history just like a regular run, but it is marked with a "Preview" label in the list so you can tell it apart from production runs.

Artifacts generated by a preview run appear in the Artifacts list, but are not indexed into the knowledge base (so they are not searchable).

After you save the workflow, the latest completed preview result is restored even if you reload the page, so you can keep reviewing it in the editor.

### Previewing the entire workflow

1. Open the editor screen.
2. In the toolbar at the bottom-right of the canvas, click **Preview** (the preview icon).
3. The run dialog opens. If user inputs are configured, review or edit the values before execution.
4. Click **Run workflow** to start.

You can check the run result in the **Output** tab of the inspector.

While a preview run is in progress, selecting the block shows a **Running** badge in the inspector header, and the **Details** tab is temporarily locked from editing until the run finishes. The **Output** tab and the delete button remain interactive.

### Previewing up to a specific block

Select the block you want to test to open its inspector.

1. Click **Preview run** in the inspector.
2. If the preview needs user inputs, review them in the dialog and start the run.
3. When the run finishes, the inspector switches to **Preview result** so you can review the block output in place.
4. Click **Back to block details** when you want to return to editing.

This runs only as far as the selected block, so it is useful when you want to verify part of the workflow quickly. Blocks outside the selected preview path are excluded from that preview, so they do not stay shown as pending results.

## Configure triggers

In the top-right of the workflow editor, click **More actions**, then click **Triggers** to configure automatic-execution triggers. You can also review and update these trigger settings from the AI Assistant or MCP tools while you build the workflow.

<figure><img src="/files/4qzOV39W17CNV7IURYbt" alt="Screenshot of trigger settings"><figcaption><p>Trigger settings</p></figcaption></figure>

### API access

By sending an HTTP request, you can start a workflow from an external system or a CI/CD pipeline.

<figure><img src="/files/VLDtDXU1iqK2YLJAmv0h" alt="Screenshot of API access settings"><figcaption><p>API access settings</p></figcaption></figure>

1. Enable the **API access** switch.
2. Under **Concurrency**, choose how Genesis should handle a new API request while an earlier API-triggered run of the same workflow is still pending or running.

| Option                     | Description                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| Run in parallel            | Start the new run and keep the earlier run going                                                |
| Cancel previous executions | Cancel older pending or running API-triggered runs of the same workflow, then start the new run |

3. Copy the **API endpoint** URL shown on screen.
4. Send a POST request that includes the API key in the `x-api-key` header.

```http
POST {API endpoint URL}
x-api-key: {API key}
Content-Type: application/json

{
  "field_name": "value"
}
```

{% hint style="info" %}
You can manage API keys from **Settings > API keys**.
{% endhint %}

### Schedule

You can run a workflow automatically on a recurring schedule.

1. Enable the **Schedule** switch.
2. Under **Frequency**, choose **Hourly**, **Daily**, **Weekdays**, **Weekly**, or **Custom**.
3. Set the minute or time, and if needed select the day of week, timezone, or a custom cron expression.
4. Review the schedule preview and the **Next runs** list, then under **Concurrency** choose how Genesis should handle a new scheduled run while an earlier scheduled run of the same workflow is still pending or running.

| Option                     | Description                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| Run in parallel            | Start the new run and keep the earlier run going                                            |
| Cancel previous executions | Cancel older pending or running scheduled runs of the same workflow, then start the new run |

5. Click **Save schedule**.

{% hint style="warning" %}
When you use **Custom**, the schedule must run at least 15 minutes apart.
{% endhint %}

{% hint style="info" %}
When the workflow is triggered by a schedule, default values are used for the workflow's user inputs.
{% endhint %}

### GitHub webhook

You can run a workflow automatically based on GitHub events.

{% hint style="warning" %}
To use GitHub Webhook triggers, GitHub must already be connected to the workspace. Connect GitHub from **Settings**.
{% endhint %}

<figure><img src="/files/141si9ZdYC3zDYh38PVj" alt="Screenshot of GitHub Webhook settings"><figcaption><p>GitHub Webhook settings</p></figcaption></figure>

1. Enable the **GitHub webhooks** switch.
2. Under **Trigger on these events**, select the events that should start the workflow.

| Event        | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| Push         | Triggered when code is pushed to a branch                   |
| Pull request | Triggered when a pull request is opened, closed, or updated |
| Release      | Triggered when a new release is published                   |

3. Under **Concurrency**, choose how Genesis should handle a new matching GitHub event while an earlier GitHub-triggered run of the same workflow is still pending or running.

| Option                     | Description                                                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Run in parallel            | Start the new run and keep the earlier run going                                                                              |
| Cancel previous executions | Cancel older pending or running GitHub-triggered runs that match the same workflow, branch, and event, then start the new run |

4. Optionally, under **Repositories**, select target repositories. If left empty, all connected repositories are targeted.
5. Optionally, under **Branches**, enter branch patterns (for example, `main`, `release/*`). If left empty, all branches are targeted.

{% hint style="info" %}
When the workflow is triggered by GitHub, default values are used for the workflow's user inputs.
{% endhint %}

## Actions during execution

While an AI Agent block is running, you can send **Feedback for the running agent** from the execution details screen. Sent feedback is queued and added before the agent's next turn, so you can steer a long-running task without stopping the run.

### Stopping a run

You can manually stop a running or waiting workflow.

1. Open the execution details screen.
2. Click **Stop**.

A stopped workflow becomes **Cancelled** in status. You can resume it later.

{% hint style="info" %}
There is no timeout on a run. Processing does not stop automatically until it completes. For long-running executions, stop the workflow manually as needed.
{% endhint %}

{% hint style="info" %}
If **Cancel previous executions** is selected for **API access**, **Schedule**, or **GitHub webhooks**, Genesis can also cancel an older run automatically when a newer matching trigger arrives. In the execution header, this appears as **Cancelled by new trigger**.
{% endhint %}

### Resuming a run

You can resume a stopped (Cancelled) workflow.

1. Open the execution details screen.
2. Click **Resume**.

If the organization is already at its concurrent execution limit when you resume, the run enters **Queued** and starts automatically when a slot frees up.

### Edit and re-run from here

While reviewing a past run, you can rewrite the prompt of a specific AI Agent block and re-run from there. Upstream block outputs are carried over, so there is no need to re-run upstream processing. The prompt edit applies only to this re-run and does not modify the workflow template itself.

1. Open the workflow execution details screen.
2. Click the AI Agent block on the graph you want to re-run.
3. In the inspector or on the graph node's hover button, click **Edit & re-run from here**.
4. Edit the prompt in the dialog, then click **Re-run workflow**.

A new run is created. Upstream block outputs and artifacts are carried over, and execution restarts from the edited block forward.

{% hint style="info" %}
Edit & re-run from here is not available from runs of archived workflows.
{% endhint %}

### Reviewing a block

If approval is configured for a block, the run enters **Review pending** after that block completes. The workflow does not move on to the next block until a reviewer takes action.

If an AI Agent block needs missing information while it is running, the run enters **Input required** instead of block review. From the alert on the execution details screen, review the request, click **Provide input**, add the missing information, and click **Resolve and continue** to resume the same run. If you cannot resolve the request, click **Stop workflow** to end the run as **Blocked**. A blocked run cannot be continued.

<figure><img src="/files/9KyfFOQyOTwc46HbkkVL" alt="Screenshot of a block waiting for review"><figcaption><p>Block review</p></figcaption></figure>

Click **Review** to open the output review screen.

* Click **Approve** to continue to the next block.
* Click **Approve with changes** to edit the block output and then approve.
* Click **Reject** to end the workflow as failed.

If a review-required block creates or updates files, those file changes stay pending until the block is approved. Review the pending file changes before you choose **Approve**, **Approve with changes**, or **Reject**.

{% hint style="info" %}
Executions waiting in **Review pending** do not consume an organization concurrency slot. After approval, a resumed run follows the same admit-or-queue behavior as other runs.
{% endhint %}

## Execution statuses

| Status         | Description                                                                        |
| -------------- | ---------------------------------------------------------------------------------- |
| Pending        | Waiting to start                                                                   |
| Running        | Currently processing                                                               |
| Review pending | Waiting for block approval                                                         |
| Input required | Waiting for additional information before the run can continue                     |
| Blocked        | Ended from an unresolved input request and cannot be continued                     |
| Completed      | All blocks finished successfully                                                   |
| Failed         | Stopped because of an error                                                        |
| Queued         | Waiting for an execution slot to open; starts automatically when capacity frees up |
| Cancelled      | Stopped manually by a user or automatically replaced by a newer matching trigger   |
| Skipped        | Excluded from execution by a Conditional block or similar                          |

{% hint style="warning" %}
If any block fails, no downstream blocks are run and the entire workflow ends with **Failed** status. There is no "continue running on block failure" option.
{% endhint %}

{% hint style="info" %}
When a loop is configured via Conditional blocks, exceeding the maximum number of iterations forces the workflow to end with an error. You can change the maximum loop count in the block settings. When unset, the default is 3.
{% endhint %}

## Troubleshooting

### User input validation errors

| Message                                                                                                                   | Cause                                               | Resolution                                            |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------- |
| The text field "{label}" cannot be empty. Please provide a value.                                                         | A required text field has no value                  | Enter a value in the field and run the workflow again |
| The number field "{label}" cannot be empty. Please provide a value.                                                       | A required text or number field has no value        | Enter a value in the field and run the workflow again |
| The file "{label}" could not be found or is no longer available. Please upload the file again or select a different file. | The uploaded file was deleted or became unavailable | Upload the file again, or select a different file     |

### Usage limit errors

| Situation                                         | Cause                                        | Resolution                                           |
| ------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------- |
| Cannot run because "Usage limit reached" is shown | The organization has reached its usage limit | Contact your administrator to request a higher limit |

### GitHub webhook errors

| Situation                                | Cause                                    | Resolution                       |
| ---------------------------------------- | ---------------------------------------- | -------------------------------- |
| Cannot enable the GitHub webhooks switch | GitHub is not connected to the workspace | Connect GitHub from **Settings** |