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

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.

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

If the workflow has no user inputs configured, a confirmation screen appears so you can enter inputs and run the workflow directly.

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.

Trigger settings

API access

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

API access settings

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

1. Copy the API endpoint URL shown on screen.

2. Send a POST request that includes the API key in the x-api-key header.

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

{
  "field_name": "value"
}

You can manage API keys from Settings > API keys.

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

1. Click Save schedule.

When you use Custom, the schedule must run at least 15 minutes apart.

When the workflow is triggered by a schedule, default values are used for the workflow's user inputs.

GitHub webhook

You can run a workflow automatically based on GitHub events.

To use GitHub Webhook triggers, GitHub must already be connected to the workspace. Connect GitHub from Settings.

GitHub Webhook settings

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

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

1. Optionally, under Repositories, select target repositories. If left empty, all connected repositories are targeted.

2. Optionally, under Branches, enter branch patterns (for example, main, release/*). If left empty, all branches are targeted.

When the workflow is triggered by GitHub, default values are used for the workflow's user inputs.

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.

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.

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.

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.

Edit & re-run from here is not available from runs of archived workflows.

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.

Block review

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.

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.

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

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.

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.

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