runs

Creates, updates, deletes, gets or lists a runs resource.

Overview

Name	runs
Type	Resource
Id	aws.omics.runs

Fields

The following fields are returned by SELECT queries:

get_run

Name	Datatype	Description
id	string	The run's ID. (pattern: <code>[0-9]+</code>)
name	string	The run's name. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
accelerators	string	The computational accelerator used to run the workflow. (GPU)
arn	string	The run's ARN. (pattern: <code>arn:.+</code>)
batch_id	string	The run's batch ID. (pattern: <code>[0-9]+</code>)
cache_behavior	string	The run cache behavior for the run. (CACHE_ON_FAILURE, CACHE_ALWAYS)
cache_id	string	The run cache associated with the run. (pattern: <code>[0-9]+</code>)
configuration	object	Configuration details for the workflow run.
creation_time	string (date-time)	When the run was created.
definition	string	The run's definition. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
digest	string	The run's digest.
engine_settings	object	The engine-specific settings for the workflow run.
engine_version	string	The actual Nextflow engine version that Amazon Web Services HealthOmics used for the run. The other workflow definition languages don't provide a value for this field. (pattern: <code>[0-9]{2}.[0-9]{2}.[0-9]</code>)
failure_reason	string	The reason a run has failed. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
log_level	string	The run's log level. (OFF, FATAL, ERROR, ALL)
log_location	object	The location of the run log.
networking_mode	string	Configuration for run networking behavior. If absent, this will default to RESTRICTED. (RESTRICTED, VPC)
output_uri	string	The run's output URI. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
parameters	object	The run's parameters.
priority	integer	The run's priority.
resource_digests	object	The run's resource digests.
retention_mode	string	The run's retention mode. (RETAIN, REMOVE)
role_arn	string	The run's service role ARN. (pattern: <code>arn:.+</code>)
run_group_id	string	The run's group ID. (pattern: <code>[0-9]+</code>)
run_id	string	The run's ID. (pattern: <code>[0-9]+</code>)
run_output_uri	string	The destination for workflow outputs. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
scratch_storage_mode	string	Optional configuration for enabling scratch ephemeral storage mounted at /tmp. If absent, this will default to SHARED. This configuration is applicable only for CPU tasks. For tasks using GPUs, scratch storage is always LOCAL. (LOCAL, SHARED)
start_time	string (date-time)	When the run started.
started_by	string	Who started the run.
status	string	The run's status. (PENDING, STARTING, RUNNING, STOPPING, COMPLETED, DELETED, CANCELLED, FAILED)
status_message	string	The run's status message. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
stop_time	string (date-time)	The run's stop time.
storage_capacity	integer	The run's storage capacity in gibibytes. For dynamic storage, after the run has completed, this value is the maximum amount of storage used during the run.
storage_type	string	The run's storage type. (STATIC, DYNAMIC)
tags	object	The run's tags.
uuid	string	The universally unique identifier for a run. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
vpc_config	object	VPC configuration for the workflow run.
workflow_id	string	The run's workflow ID. (pattern: <code>[0-9]+</code>)
workflow_owner_id	string	The ID of the workflow owner. (pattern: <code>[0-9]{12}</code>)
workflow_type	string	The run's workflow type. (PRIVATE, READY2RUN)
workflow_uuid	string	The universally unique identifier (UUID) value for the workflow. (pattern: <code>[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}</code>)
workflow_version_name	string	The workflow version name. (pattern: <code>[A-Za-z0-9][A-Za-z0-9-._]*</code>)

list_runs

Name	Datatype	Description
id	string	The run's ID. (pattern: <code>[0-9]+</code>)
name	string	The run's name. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
arn	string	The run's ARN. (pattern: <code>arn:.+</code>)
batch_id	string	The run's batch ID. (pattern: <code>[0-9]+</code>)
creation_time	string (date-time)	When the run was created.
priority	integer	The run's priority.
start_time	string (date-time)	When the run started.
status	string	The run's status. (PENDING, STARTING, RUNNING, STOPPING, COMPLETED, DELETED, CANCELLED, FAILED)
stop_time	string (date-time)	When the run stopped.
storage_capacity	integer	The run's storage capacity in gibibytes. For dynamic storage, after the run has completed, this value is the maximum amount of storage used during the run.
storage_type	string	The run's storage type. (STATIC, DYNAMIC)
workflow_id	string	The run's workflow ID. (pattern: <code>[0-9]+</code>)
workflow_name	string	The name of the workflow. (pattern: <code>[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+</code>)
workflow_version_name	string	The name of the workflow version. (pattern: <code>[A-Za-z0-9][A-Za-z0-9-._]*</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_run	select	id, region	export	Gets detailed information about a specific run using its ID. Amazon Web Services HealthOmics stores a configurable number of runs, as determined by service limits, that are available to the console and API. If GetRun does not return the requested run, you can find all run logs in the CloudWatch logs. For more information about viewing the run logs, see CloudWatch logs in the Amazon Web Services HealthOmics User Guide.
list_runs	select	region	name, runGroupId, batchId, startingToken, maxResults, status	Retrieves a list of runs and returns each run's metadata and status. Amazon Web Services HealthOmics stores a configurable number of runs, as determined by service limits, that are available to the console and API. If the ListRuns response doesn't include specific runs that you expected, you can find all run logs in the CloudWatch logs. For more information about viewing the run logs, see CloudWatch logs in the Amazon Web Services HealthOmics User Guide.
delete_run	delete	id, region		Deletes a run and returns a response with no body if the operation is successful. You can only delete a run that has reached a COMPLETED, FAILED, or CANCELLED stage. A completed run has delivered an output, or was cancelled and resulted in no output. When you delete a run, only the metadata associated with the run is deleted. The run outputs remain in Amazon S3 and logs remain in CloudWatch. To verify that the workflow is deleted: Use ListRuns to confirm the workflow no longer appears in the list. Use GetRun to verify the workflow cannot be found.
cancel_run_batch	exec	region, batchId		Cancels all runs within a specified batch. This operation prevents not-yet-submitted runs from starting and submits CancelRun requests for runs that have already started. Cancel is only allowed on batches in PENDING, SUBMITTING, or INPROGRESS state. Cancel operations are non-atomic and may be partially successful. Use GetBatch to review successfulCancelSubmissionCount and failedCancelSubmissionCount in the submissionSummary. Only one cancel or delete operation per batch is allowed at a time.
start_run_batch	exec	region, requestId, defaultRunSetting, batchRunSettings		Starts a batch of workflow runs. You can group up to 100,000 runs into a single batch that share a common configuration defined in defaultRunSetting. Per-run overrides can be provided either inline via inlineSettings (up to 100 runs) or via a JSON file stored in Amazon S3 via s3UriSettings (up to 100,000 runs). StartRunBatch validates common fields synchronously and returns immediately with a batch ID and status CREATING. The batch transitions to PENDING once initial setup completes. Runs are then submitted gradually and asynchronously at a rate governed by your StartRun throughput quota.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
id	string	The run's ID.
region	string	AWS region (default: us-east-1)
batchId	string	Filter by batch ID.
export	array	The run's export format.
maxResults	integer	The maximum number of runs to return in one page of results.
name	string	Filter the list by run name.
runGroupId	string	Filter the list by run group ID.
startingToken	string	Specify the pagination token from a previous request to retrieve the next page of results.
status	string	The status of a run.

SELECT examples

get_run

Gets detailed information about a specific run using its ID. Amazon Web Services HealthOmics stores a configurable number of runs, as determined by service limits, that are available to the console and API. If GetRun does not return the requested run, you can find all run logs in the CloudWatch logs. For more information about viewing the run logs, see CloudWatch logs in the Amazon Web Services HealthOmics User Guide.

SELECT
id,
name,
accelerators,
arn,
batch_id,
cache_behavior,
cache_id,
configuration,
creation_time,
definition,
digest,
engine_settings,
engine_version,
failure_reason,
log_level,
log_location,
networking_mode,
output_uri,
parameters,
priority,
resource_digests,
retention_mode,
role_arn,
run_group_id,
run_id,
run_output_uri,
scratch_storage_mode,
start_time,
started_by,
status,
status_message,
stop_time,
storage_capacity,
storage_type,
tags,
uuid,
vpc_config,
workflow_id,
workflow_owner_id,
workflow_type,
workflow_uuid,
workflow_version_name
FROM aws.omics.runs
WHERE id = '{{ id }}' -- required
AND region = '{{ region }}' -- required
AND export = '{{ export }}'
;

list_runs

Retrieves a list of runs and returns each run's metadata and status. Amazon Web Services HealthOmics stores a configurable number of runs, as determined by service limits, that are available to the console and API. If the ListRuns response doesn't include specific runs that you expected, you can find all run logs in the CloudWatch logs. For more information about viewing the run logs, see CloudWatch logs in the Amazon Web Services HealthOmics User Guide.

SELECT
id,
name,
arn,
batch_id,
creation_time,
priority,
start_time,
status,
stop_time,
storage_capacity,
storage_type,
workflow_id,
workflow_name,
workflow_version_name
FROM aws.omics.runs
WHERE region = '{{ region }}' -- required
AND name = '{{ name }}'
AND runGroupId = '{{ runGroupId }}'
AND batchId = '{{ batchId }}'
AND startingToken = '{{ startingToken }}'
AND maxResults = '{{ maxResults }}'
AND status = '{{ status }}'
;

DELETE examples

delete_run

Deletes a run and returns a response with no body if the operation is successful. You can only delete a run that has reached a COMPLETED, FAILED, or CANCELLED stage. A completed run has delivered an output, or was cancelled and resulted in no output. When you delete a run, only the metadata associated with the run is deleted. The run outputs remain in Amazon S3 and logs remain in CloudWatch. To verify that the workflow is deleted: Use ListRuns to confirm the workflow no longer appears in the list. Use GetRun to verify the workflow cannot be found.

DELETE FROM aws.omics.runs
WHERE id = '{{ id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

cancel_run_batch

Cancels all runs within a specified batch. This operation prevents not-yet-submitted runs from starting and submits CancelRun requests for runs that have already started. Cancel is only allowed on batches in PENDING, SUBMITTING, or INPROGRESS state. Cancel operations are non-atomic and may be partially successful. Use GetBatch to review successfulCancelSubmissionCount and failedCancelSubmissionCount in the submissionSummary. Only one cancel or delete operation per batch is allowed at a time.

EXEC aws.omics.runs.cancel_run_batch 
@region='{{ region }}' --required 
@@json=
'{
"batchId": "{{ batchId }}"
}'
;

start_run_batch

Starts a batch of workflow runs. You can group up to 100,000 runs into a single batch that share a common configuration defined in defaultRunSetting. Per-run overrides can be provided either inline via inlineSettings (up to 100 runs) or via a JSON file stored in Amazon S3 via s3UriSettings (up to 100,000 runs). StartRunBatch validates common fields synchronously and returns immediately with a batch ID and status CREATING. The batch transitions to PENDING once initial setup completes. Runs are then submitted gradually and asynchronously at a rate governed by your StartRun throughput quota.

EXEC aws.omics.runs.start_run_batch 
@region='{{ region }}' --required 
@@json=
'{
"batchName": "{{ batchName }}", 
"requestId": "{{ requestId }}", 
"tags": "{{ tags }}", 
"defaultRunSetting": "{{ defaultRunSetting }}", 
"batchRunSettings": "{{ batchRunSettings }}"
}'
;