Start a run in HealthOmics

When you start a run, you specify the resources that HealthOmics allocates for the run. The following settings are available:

Starting a run using the console

The Start run wizard has four steps:

To start a run

Step 1: Specify run details

Provide the following settings:

Choose Next to proceed to Step 2.

Step 2: Add parameter values

On this page, enter the parameter values for the run, or select predefined values provided by the workflow author.

When you select a Nextflow workflow to start the run, additional sections for Nextflow engine settings and Nextflow profiles appear at the top of this step. For complete details on these settings (supported values, behavior, and profile precedence), see Specify Nextflow engine settings.

Run parameter values

Provide the run parameters. You can upload a JSON file or manually enter the values. The JSON file contains the exact name of each input parameter and a value for the parameter.

HealthOmics supports the following JSON types for parameter values.

For more information, see HealthOmics run inputs and Managing run parameters size.

Choose Next to proceed to Step 3.

Step 3: Add run group, run cache, and tags

All settings on this page are optional.

Choose Next to proceed to Step 4.

Step 4: Review and start run

Review the run configuration from all previous steps. To modify a setting, choose Edit next to the relevant step. When you're ready, choose Start run.

Starting a run using the API

Use the StartRun API operation to create and start a run.

Start a basic run

The following example specifies the workflow ID, service role, and output URI. This example sets the retention mode to REMOVE. For more information about retention mode, see Run retention mode for HealthOmics runs.

aws omics start-run \
     --workflow-id workflow id \
     --role-arn arn:aws:iam::123456789012:role/OmicsRole \
     --output-uri s3://amzn-s3-demo-bucket/output \
     --name "my-workflow-run" \
     --retention-mode REMOVE

In response, you get the following output. The uuid is unique to the run, and along with outputUri can be used to track where output data is written.

{
    "arn": "arn:aws:omics:us-west-2:123456789012:run/1234567",
    "id": "123456789",
    "uuid": "96c57683-74bf-9d6d-ae7e-f09b097db14a",
    "outputUri": "s3://bucket/folder/8405154/96c57683-74bf-9d6d-ae7e-f09b097db14a",
    "status": "PENDING"
}

Common API options

Include a parameter file

If the parameter template for a workflow declares any required parameters, you can provide a local JSON file of the inputs when you start a workflow run. The JSON file contains the exact name of each input parameter and a value for the parameter.

Reference the input JSON file in the AWS CLI by adding --parameters file://<input_file.json> to your start-run request. For more information, see supported JSON types for parameter values in Step 2: Add parameter values and HealthOmics run inputs.

Provide a request ID

You can provide a unique requestId for each run. The request ID is an idempotency token that HealthOmics uses to catch duplicate requests. It won't start a run if the request ID is a duplicate of a previous run.

If you use infrastructure (such as Lambda functions or step functions) for orchestrating run starts, best practice is to provide a unique request ID for each StartRun request. This ensures that if your infrastructure inadvertently starts a run that it already started, HealthOmics won't start the duplicate run.

aws omics start-run \
     --workflow-id workflow id \
     ... \
     --request-id "unique-request-id-12345"

Choose a workflow version

You can specify a workflow version for the run. If you don't specify a version, HealthOmics starts the run with the default workflow version.

aws omics start-run \
     --workflow-id workflow id \
     ... \
     --workflow-version-name '1.2.1'

Override the run storage type

You can override the default run storage type that was set in the workflow.

aws omics start-run \
     --workflow-id workflow id \
     ... \
     --storage-type STATIC \
     --storage-capacity 2400

Enabling ephemeral storage

To enable ephemeral storage for a run, set --scratch-storage-mode to LOCAL when you start the run. HealthOmics mounts a dedicated local storage volume at /tmp for each workflow task instance.

aws omics start-run \
    --workflow-id workflow-id \
    --role-arn arn:aws:iam::123456789012:role/OmicsServiceRole \
    --output-uri s3://amzn-s3-demo-bucket/output-folder/ \
    --parameters file:///path/to/parameters.json \
    --scratch-storage-mode LOCAL

To disable ephemeral storage for a specific run (for example, to isolate a failure), set --scratch-storage-mode to SHARED.

For more information, see Ephemeral storage for HealthOmics workflow tasks.

For Nextflow engine settings (engine version, profiles, syntax parser), see Specify Nextflow engine settings.

Specify Nextflow engine settings

For Nextflow workflows, you can pass an engineSettings map in the StartRun API request to control engine behavior without modifying your workflow source code. On the console, these settings are available in Step 2: Add parameter values as a separate section that appears for Nextflow workflows.

Supported keys

Nextflow engine version pinning

You can select a specific Nextflow engine version to run your workflow, enabling controlled migration across engine versions. The run-time version override ensures that even when a workflow definition specifies a version through its config or profile, the engine version that you specify at run time takes precedence. This enables you to test the same workflow across multiple engine versions without modifying the workflow source code.

Supported versions: 22.04.0 (or 22.04), 23.10.0 (or 23.10), 24.10.8 (or 24.10), 25.10.0 (or 25.10), and 26.04.0 (or 26.04). Both full and short version formats are accepted.

API and CLI

Use the engineVersion key in --engine-settings:

aws omics start-run \
    --workflow-id workflow id \
    --role-arn arn:aws:iam::123456789012:role/OmicsRole \
    --output-uri s3://amzn-s3-demo-bucket/output \
    --engine-settings '{"engineVersion":"26.04"}'

Console

In Step 2: Add parameter values, select the version from the Engine version dropdown in the Nextflow engine settings section.

Nextflow profiles

Nextflow profiles are named sets of execution settings defined in your workflow's nextflow.config. You can activate one or more profiles at run time to apply environment-specific settings (for example, development, test, or production) without modifying the workflow source code.

API and CLI

Use the profile key in --engine-settings. Specify multiple profiles as a comma-separated list:

aws omics start-run \
    --workflow-id workflow id \
    --role-arn arn:aws:iam::123456789012:role/OmicsRole \
    --output-uri s3://amzn-s3-demo-bucket/output \
    --engine-settings '{"profile":"test,docker"}'

Console

In Step 2: Add parameter values, the Nextflow profiles section appears below the engine settings. Select one or more profiles from the Select profiles dropdown. The console displays the profile application order. To remove a profile, choose the × next to its name.

Profile application order

When you specify multiple profiles, the application order depends on the Nextflow engine version and syntax parser:

Configuration precedence

Nextflow resolves parameters in the following order, with later layers overriding earlier ones:

VPC networking

You can run workflows in your Virtual Private Cloud (VPC), which enables access to the public internet, cross-Region traffic, and communication with resources in your VPC.

To enable VPC networking:

For more information, see Connecting HealthOmics workflows to a VPC.