> 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**.
{% 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).

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

Click **Preview** (the preview icon) to the left of a block to preview-run only up to that block. This is useful when you want to verify part of the workflow.

<figure><img src="/files/N8MuWFvcJUI1UBgPdCD1" alt="Screenshot of the preview-up-to-a-block button"><figcaption><p>Preview up to a specific block</p></figcaption></figure>

## Configure triggers

In the top-right of the workflow editor, click **More actions**, then click **Triggers** to configure automatic-execution triggers.

<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

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

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

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

## Execution statuses

| Status         | Description                                                                      |
| -------------- | -------------------------------------------------------------------------------- |
| Pending        | Waiting to start                                                                 |
| Running        | Currently processing                                                             |
| Review pending | Waiting for block approval                                                       |
| Completed      | All blocks finished successfully                                                 |
| Failed         | Stopped because of an error                                                      |
| 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** |


---

# 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, and the optional `goal` query parameter:

```
GET https://help.genesis.autify.com/workflow/workflow-execution.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.