logo
API docs by Redocly

Workflow Execution Service (1.2.0)

Download OpenAPI specification:Download

Run standard workflows on workflow execution platforms in a platform-agnostic way.

Executive Summary

The Workflow Execution Service (WES) API provides a standard way for users to submit workflow requests to workflow execution systems, and to monitor their execution. This API lets users run a single workflow (commonly CWL, WDL, Nextflow, and Snakemake formatted workflows, WES servers describe what they support via service-info) on multiple different platforms, clouds, and environments.

Key features of the API:

  • can request that a workflow be run
  • can pass parameters to that workflow (e.g. input files, cmdline arguments) via both workflow-type specific parameter formats as well as a generalized parameter JSON format
  • can get information about running workflows (e.g. status, errors, output file locations)
  • can cancel a running workflow
  • can retrieve logs and outputs file locations from a workflow run

Introduction

This document describes the WES API and provides details on the specific endpoints, request formats, and responses. It is intended to provide key information for developers of WES-compatible services as well as clients that will call these WES services.

Use cases include:

  • "Bring your code to the data": a researcher who has built their own custom analysis workflow can submit it to run on a dataset owned by an external organization, instead of having to download a copy of the data for local analysis.
  • Best-practices pipelines: a researcher who maintains their own controlled data environment can find useful workflows in a shared repository (e.g. Dockstore.org), and run them on their data

Standards

The WES API specification is written in OpenAPI and embodies a RESTful service philosophy. It uses JSON in requests and responses (where applicable) and standard HTTP/HTTPS for information transport.

Authorization & Authentication

Users must supply credentials that establish their identity and authorization in order to use a WES endpoint. We recommend that WES implementations use an OAuth2 bearer token, although they can choose other mechanisms if appropriate. WES callers can use the auth_instructions_url from the service-info endpoint to learn how to obtain and use a bearer token for a particular implementation.

The WES implementation is responsible for checking that a user is authorized to submit workflow run requests. The particular authorization policy is up to the WES implementer.

Systems like WES need to also address the ability to pass credentials with jobs for input and output access. In the current version of WES, the passing of credentials to authenticate and authorize access to inputs and outputs, as well as mandates about necessary file transfer protocols to support, are out of scope. However, parallel work on the GA4GH Data Repository Service is addressing ways to pass around access credentials with data object references, opening up the possibility that a future version of WES will provide concrete mechanisms for workflow runs to access data using credentials different than those used for WES calls. This is a work in progress and support of DRS in WES will be added in a future release of WES.

Service Info

Get information about the workflow execution service

GetServiceInfo

Includes information related, but not limited to, the workflow descriptor formats, workflow engines, versions supported, the WES API versions supported, and information about general service availability and access.

Responses

Response samples

Content type
application/json
{
  • "id": "org.ga4gh.myservice",
  • "name": "My project",
  • "type": {
    },
  • "description": "This service provides...",
  • "organization": {},
  • "contactUrl": "mailto:support@example.com",
  • "documentationUrl": "https://docs.myservice.example.com",
  • "createdAt": "2019-06-04T12:58:19Z",
  • "updatedAt": "2019-06-04T12:58:19Z",
  • "environment": "test",
  • "version": "1.0.0",
  • "workflow_type": {
    },
  • "workflow_type_versions": {
    },
  • "supported_wes_versions": [
    ],
  • "supported_filesystem_protocols": [
    ],
  • "workflow_engine": {
    },
  • "workflow_engine_versions": {
    },
  • "default_workflow_engine_parameters": [
    ],
  • "system_state_counts": {
    },
  • "auth_instructions_url": "string",
  • "tags": {
    }
}

Workflow Runs

Submit and monitor workflows in a WES environment

ListRuns

This list should be provided in a stable ordering. (The actual ordering is implementation dependent.) When paging through the list, the client should not make assumptions about live updates, but should assume the contents of the list reflect the workflow list at the moment that the first page is requested. To monitor a specific workflow run, use GetRunStatus or GetRunLog.

Authorizations:
BearerAuthNone
query Parameters
page_size
integer <int64>

OPTIONAL The preferred number of workflow runs to return in a page. If not provided, the implementation should use a default page size. The implementation must not return more items than page_size, but it may return fewer. Clients should not assume that if fewer than page_size items are returned that all items have been returned. The availability of additional pages is indicated by the value of next_page_token in the response.

page_token
string

OPTIONAL Token to use to indicate where to start getting results. If unspecified, return the first page of results.

Responses

Response samples

Content type
application/json
{
  • "runs": [
    ],
  • "next_page_token": "string"
}

RunWorkflowOrListRuns

This endpoint supports two operations based on the request body content:

  1. Submit Workflow Run: When request body contains RunRequest schema, creates a new workflow run and returns a RunId to monitor its progress.

  2. List Runs with Passport: When request body contains RunsListRequest schema with GA4GH passport authentication, returns a list of workflow runs (same as GET /runs but with passport auth).

Workflow Submission (RunRequest):

Content Types Supported:

  1. application/json (Recommended for workflows submitted by URLs): Submit a complete RunRequest object with structured data and type validation. The advantage of this approach is the schema is explicitly defined by OpenAPI syntax (vs. just strings in multipart-form) along with workflow_unified_params object support (see below for more info). Disadvantage is that it does not support workflow file uploads directly, which may be required for multi-file workflows not available as URLs.

  2. multipart/form-data: Submit for cases requiring workflow file uploads (rather than just a URL). Fields are JSON-encoded strings that mirror the RunRequest structure. Advantage is you can upload one or more workflow files directly while the disadvantage is you need to be careful in formatting the JSON-encoded string arguments correctly (multipart form submissions only support strings hence the limitation).

File Handling:

  • application/json requests: Workflow file is referenced by URL or path via workflow_url with additional workflow files specified by additional_workflow_urls. Use workflow_unified_params for generic workflow parameterization (recommended when possible) or workflow_params for JSON-string encoded native workflow params passing.

  • multipart/form-data requests: The workflow_attachment array uploads files required for workflow execution. Files are staged to a temporary directory with Content-Disposition headers containing filenames. Subdirectories are allowed but parent directory references ('..') are prohibited for security purposes. Use workflow_unified_params for generic workflow parameterization (recommended when possible) or workflow_params for JSON-string encoded native workflow params passing.

Parameter Formats:

  • workflow_params: Language-specific parameters (CWL, WDL, Nextflow, Snakemake format). This field is used to send the native parameterization file (encoded as a JSON string) used by the workflow engine.

  • workflow_unified_params: Universal parameter format that the WES server implementation converts to the target workflow language parameterization format. This allows for a more generic way to pass parameters that can be converted to the appropriate native format for the specified workflow_type. This is an optional field (and the recommended way to pass params). If provided, it takes precedence over workflow_params.

Required Fields:

  • workflow_type: Workflow language ("CWL", "WDL", "Nextflow", "Snakemake", or another alternative supported by this WES instance, see service-info)

  • workflow_type_version: The workflow descriptor type version, must be one supported by this WES instance, see service-info

  • workflow_url: Absolute URL to primary workflow file, or relative path to uploaded attachment

See the RunRequest schema documentation for complete field descriptions and validation rules when encoding as strings in the multipart/form-data request.

Authorizations:
BearerAuthPassportAuthNone
Request Body schema:
One of
passport
Array of strings <jwt> non-empty

Array of GA4GH passport JWTs for authentication and authorization

workflow_params
object

OPTIONAL The workflow run parameterizations (JSON encoded), including input and output file locations. Either workflow_params or workflow_unified_params must be provided, workflow_unified_params takes precedence.

object

OPTIONAL Unified parameter format that can be converted to workflow-language-specific format. If provided, takes precedence over workflow_params. WES implementations should convert these to the appropriate native format for the specified workflow_type.

workflow_type
required
string

REQUIRED Workflow descriptor type, must be "CWL", "WDL", "Nextflow", or "Snakemake" currently (or another alternative supported by this WES instance, see service-info for supported types)

workflow_type_version
required
string

REQUIRED The workflow descriptor type version, must be one supported by this WES instance (see service-info for supported versions)

object

OPTIONAL Arbitrary key-value tags to associate with the workflow run for organization, tracking, or metadata purposes. Examples include experiment names, user identifiers, sample IDs, or project codes.

object
workflow_engine
string

OPTIONAL The workflow engine, must be one supported by this WES instance (see service-info for supported engines). Required if workflow_engine_version is provided.

workflow_engine_version
string

OPTIONAL The workflow engine version, must be one supported by this WES instance (see service-info for supported engine versions). If workflow_engine is provided, but workflow_engine_version is not, servers can make no assumptions with regard to the engine version the WES instance uses to process the request if that WES instance supports multiple versions of the requested engine.

workflow_url
required
string

REQUIRED The primary workflow document. When workflow_attachments is used to attach files, the workflow_url may be a relative path to one of the attachments that is the primary workflow to be executed.

Array of objects

OPTIONAL Additional workflow files required for execution (e.g., imported workflows, subworkflows, or dependencies). Each entry specifies both the source URL and target file path for precise file placement.

object

OPTIONAL Named credentials that can be referenced by input parameters that require authentication to access File or Directory resources. Each credential is identified by a unique key and can be referenced multiple times by different parameters to avoid duplicating large authentication tokens.

Responses

Request samples

Content type
Example
{
  • "passport": [
    ],
  • "workflow_params": { },
  • "workflow_unified_params": {
    },
  • "workflow_type": "string",
  • "workflow_type_version": "string",
  • "tags": {
    },
  • "workflow_engine_parameters": {
    },
  • "workflow_engine": "string",
  • "workflow_engine_version": "string",
  • "workflow_url": "string",
  • "additional_workflow_urls": [
    ],
  • "credentials": {
    }
}

Response samples

Content type
application/json
Example
{
  • "run_id": "string"
}

GetRunLog

This endpoint provides detailed information about a given workflow run. The returned result has information about the outputs produced by this workflow (if available), a log object which allows the stderr and stdout to be retrieved, a log array so stderr/stdout for individual tasks can be retrieved, and the overall state of the workflow run (e.g. RUNNING, see the State section).

Authorizations:
BearerAuthNone
path Parameters
run_id
required
string

Responses

Response samples

Content type
application/json
{
  • "run_id": "string",
  • "request": {
    },
  • "state": "UNKNOWN",
  • "run_log": {
    },
  • "task_logs_url": "string",
  • "task_logs": [
    ],
  • "outputs": { },
  • "structured_outputs": {
    },
  • "output_credentials": {
    }
}

GetRunLogWithPassport

Same as GetRunLog but supports GA4GH passport authentication via POST body. This endpoint provides detailed information about a given workflow run.

Authorizations:
PassportAuthNone
path Parameters
run_id
required
string
Request Body schema: application/json
passport
required
Array of strings <jwt> non-empty

Array of GA4GH passport JWTs for authentication and authorization

Responses

Request samples

Content type
application/json
{
  • "passport": [
    ]
}

Response samples

Content type
application/json
{
  • "run_id": "string",
  • "request": {
    },
  • "state": "UNKNOWN",
  • "run_log": {
    },
  • "task_logs_url": "string",
  • "task_logs": [
    ],
  • "outputs": { },
  • "structured_outputs": {
    },
  • "output_credentials": {
    }
}

GetRunStatus

This provides an abbreviated (and likely fast depending on implementation) status of the running workflow, returning a simple result with the overall state of the workflow run (e.g. RUNNING, see the State section).

Authorizations:
BearerAuthNone
path Parameters
run_id
required
string

Responses

Response samples

Content type
application/json
{
  • "run_id": "string",
  • "state": "UNKNOWN"
}

GetRunStatusWithPassport

Same as GetRunStatus but supports GA4GH passport authentication via POST body. This provides an abbreviated status of the running workflow.

Authorizations:
PassportAuthNone
path Parameters
run_id
required
string
Request Body schema: application/json
passport
required
Array of strings <jwt> non-empty

Array of GA4GH passport JWTs for authentication and authorization

Responses

Request samples

Content type
application/json
{
  • "passport": [
    ]
}

Response samples

Content type
application/json
{
  • "run_id": "string",
  • "state": "UNKNOWN"
}

ListTasks

This endpoint provides a paginated list of tasks that were executed as part of a given workflow run. Task ordering should be the same as what would be returned in a RunLog response body.

Authorizations:
BearerAuthNone
path Parameters
run_id
required
string
query Parameters
page_size
integer <int64>

OPTIONAL The preferred number of task logs to return in a page. If not provided, the implementation should use a default page size. The implementation must not return more items than page_size, but it may return fewer. Clients should not assume that if fewer than page_size items are returned that all items have been returned. The availability of additional pages is indicated by the value of next_page_token in the response.

page_token
string

OPTIONAL Token to use to indicate where to start getting results. If unspecified, return the first page of results.

Responses

Response samples

Content type
application/json
{
  • "task_logs": [
    ],
  • "next_page_token": "string"
}

ListTasksWithPassport

Same as ListTasks but supports GA4GH passport authentication via POST body. This endpoint provides a paginated list of tasks that were executed as part of a given workflow run.

Authorizations:
PassportAuthNone
path Parameters
run_id
required
string
Request Body schema: application/json
passport
required
Array of strings <jwt> non-empty

Array of GA4GH passport JWTs for authentication and authorization

page_size
integer <int64>

OPTIONAL The preferred number of task logs to return in a page.

page_token
string

OPTIONAL Token to use to indicate where to start getting results.

Responses

Request samples

Content type
application/json
{
  • "passport": [
    ],
  • "page_size": 0,
  • "page_token": "string"
}

Response samples

Content type
application/json
{
  • "task_logs": [
    ],
  • "next_page_token": "string"
}

GetTask

This endpoint provides a mechanism to retrieve information on a specific task, if it exists

Authorizations:
BearerAuthNone
path Parameters
run_id
required
string
task_id
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "cmd": [
    ],
  • "start_time": "string",
  • "end_time": "string",
  • "stdout": "string",
  • "stderr": "string",
  • "exit_code": 0,
  • "system_logs": [
    ],
  • "id": "string",
  • "tes_uri": "string"
}

GetTaskWithPassport

Same as GetTask but supports GA4GH passport authentication via POST body. This endpoint provides information on a specific task.

Authorizations:
PassportAuthNone
path Parameters
run_id
required
string
task_id
required
string
Request Body schema: application/json
passport
required
Array of strings <jwt> non-empty

Array of GA4GH passport JWTs for authentication and authorization

Responses

Request samples

Content type
application/json
{
  • "passport": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "cmd": [
    ],
  • "start_time": "string",
  • "end_time": "string",
  • "stdout": "string",
  • "stderr": "string",
  • "exit_code": 0,
  • "system_logs": [
    ],
  • "id": "string",
  • "tes_uri": "string"
}

CancelRun

Cancel a running workflow.

Authorizations:
BearerAuthPassportAuthNone
path Parameters
run_id
required
string
Request Body schema: application/json
passport
Array of strings <jwt> non-empty

Array of GA4GH passport JWTs for authentication and authorization

Responses

Request samples

Content type
application/json
{
  • "passport": [
    ]
}

Response samples

Content type
application/json
{
  • "run_id": "string"
}

ServiceInfo

id
required
string

Unique ID of this service. Reverse domain name notation is recommended, though not required. The identifier should attempt to be globally unique so it can be used in downstream aggregator services e.g. Service Registry.

name
required
string

Name of this service. Should be human readable.

required
object (ServiceType)

Type of a GA4GH service

description
string

Description of the service. Should be human readable and provide information about the service.

required
object

Organization providing the service

contactUrl
string <uri>

URL of the contact for the provider of this service, e.g. a link to a contact form (RFC 3986 format), or an email (RFC 2368 format).

documentationUrl
string <uri>

URL of the documentation of this service (RFC 3986 format). This should help someone learn how to use your service, including any specifics required to access data, e.g. authentication.

createdAt
string <date-time>

Timestamp describing when the service was first deployed and available (RFC 3339 format)

updatedAt
string <date-time>

Timestamp describing when the service was last updated (RFC 3339 format)

environment
string

Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments. Suggested values are prod, test, dev, staging. However this is advised and not enforced.

version
required
string

Version of the service being described. Semantic versioning is recommended, but other identifiers, such as dates or commit hashes, are also allowed. The version should be changed whenever the service is updated.

object
required
object
supported_wes_versions
required
Array of strings

The version(s) of the WES schema supported by this service

supported_filesystem_protocols
required
Array of strings

The filesystem protocols supported by this service, currently these may include common protocols using the terms 'http', 'https', 'sftp', 's3', 'gs', 'file', or 'synapse', but others are possible and the terms beyond these core protocols are currently not fixed. This section reports those protocols (either common or not) supported by this WES service.

object
required
object
required
Array of objects (DefaultWorkflowEngineParameter)

Each workflow engine can present additional parameters that can be sent to the workflow engine. This message will list the default values, and their types for each workflow engine.

required
object
auth_instructions_url
required
string

A web page URL with human-readable instructions on how to get an authorization token for use with a specific WES endpoint.

required
object
{
  • "id": "org.ga4gh.myservice",
  • "name": "My project",
  • "type": {
    },
  • "description": "This service provides...",
  • "organization": {},
  • "contactUrl": "mailto:support@example.com",
  • "documentationUrl": "https://docs.myservice.example.com",
  • "createdAt": "2019-06-04T12:58:19Z",
  • "updatedAt": "2019-06-04T12:58:19Z",
  • "environment": "test",
  • "version": "1.0.0",
  • "workflow_type": {
    },
  • "workflow_type_versions": {
    },
  • "supported_wes_versions": [
    ],
  • "supported_filesystem_protocols": [
    ],
  • "workflow_engine": {
    },
  • "workflow_engine_versions": {
    },
  • "default_workflow_engine_parameters": [
    ],
  • "system_state_counts": {
    },
  • "auth_instructions_url": "string",
  • "tags": {
    }
}

RunListResponse

Array of RunStatus (object) or RunSummary (object)

A list of workflow runs that the service has executed or is executing. The list is filtered to only include runs that the caller has permission to see.

next_page_token
string

A token which may be supplied as page_token in workflow run list request to get the next page of results. An empty string indicates there are no more items to return.

{
  • "runs": [
    ],
  • "next_page_token": "string"
}

RunId

run_id
string

workflow run ID

{
  • "run_id": "string"
}

State

string (State)
Enum: "UNKNOWN" "QUEUED" "INITIALIZING" "RUNNING" "PAUSED" "COMPLETE" "EXECUTOR_ERROR" "SYSTEM_ERROR" "CANCELED" "CANCELING" "PREEMPTED"

State can take any of the following values:

  • UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing, for example, so that a missing field does not accidentally imply that the state is QUEUED.

  • QUEUED: The task is queued.

  • INITIALIZING: The task has been assigned to a worker and is currently preparing to run. For example, the worker may be turning on, downloading input files, etc.

  • RUNNING: The task is running. Input files are downloaded and the first Executor has been started.

  • PAUSED: The task is paused. An implementation may have the ability to pause a task, but this is not required.

  • COMPLETE: The task has completed running. Executors have exited without error and output files have been successfully uploaded.

  • EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally, this means that an Executor exited with a non-zero exit code.

  • SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor, for example an upload failed due to network issues, the worker's ran out of disk space, etc.

  • CANCELED: The task was canceled by the user.

  • CANCELING: The task was canceled by the user, and is in the process of stopping.

  • PREEMPTED: The task is stopped (preempted) by the system. The reasons for this would be tied to the specific system running the job. Generally, this means that the system reclaimed the compute capacity for reallocation.

"UNKNOWN"

RunStatus

run_id
required
string
state
string (State)
Enum: "UNKNOWN" "QUEUED" "INITIALIZING" "RUNNING" "PAUSED" "COMPLETE" "EXECUTOR_ERROR" "SYSTEM_ERROR" "CANCELED" "CANCELING" "PREEMPTED"

State can take any of the following values:

  • UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing, for example, so that a missing field does not accidentally imply that the state is QUEUED.

  • QUEUED: The task is queued.

  • INITIALIZING: The task has been assigned to a worker and is currently preparing to run. For example, the worker may be turning on, downloading input files, etc.

  • RUNNING: The task is running. Input files are downloaded and the first Executor has been started.

  • PAUSED: The task is paused. An implementation may have the ability to pause a task, but this is not required.

  • COMPLETE: The task has completed running. Executors have exited without error and output files have been successfully uploaded.

  • EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally, this means that an Executor exited with a non-zero exit code.

  • SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor, for example an upload failed due to network issues, the worker's ran out of disk space, etc.

  • CANCELED: The task was canceled by the user.

  • CANCELING: The task was canceled by the user, and is in the process of stopping.

  • PREEMPTED: The task is stopped (preempted) by the system. The reasons for this would be tied to the specific system running the job. Generally, this means that the system reclaimed the compute capacity for reallocation.

{
  • "run_id": "string",
  • "state": "UNKNOWN"
}

RunSummary

run_id
required
string
state
string (State)
Enum: "UNKNOWN" "QUEUED" "INITIALIZING" "RUNNING" "PAUSED" "COMPLETE" "EXECUTOR_ERROR" "SYSTEM_ERROR" "CANCELED" "CANCELING" "PREEMPTED"

State can take any of the following values:

  • UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing, for example, so that a missing field does not accidentally imply that the state is QUEUED.

  • QUEUED: The task is queued.

  • INITIALIZING: The task has been assigned to a worker and is currently preparing to run. For example, the worker may be turning on, downloading input files, etc.

  • RUNNING: The task is running. Input files are downloaded and the first Executor has been started.

  • PAUSED: The task is paused. An implementation may have the ability to pause a task, but this is not required.

  • COMPLETE: The task has completed running. Executors have exited without error and output files have been successfully uploaded.

  • EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally, this means that an Executor exited with a non-zero exit code.

  • SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor, for example an upload failed due to network issues, the worker's ran out of disk space, etc.

  • CANCELED: The task was canceled by the user.

  • CANCELING: The task was canceled by the user, and is in the process of stopping.

  • PREEMPTED: The task is stopped (preempted) by the system. The reasons for this would be tied to the specific system running the job. Generally, this means that the system reclaimed the compute capacity for reallocation.

start_time
string

When the run started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"

end_time
string

When the run stopped executing (completed, failed, or cancelled), in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"

required
object

Arbitrary key/value tags added by the client during run creation

{
  • "run_id": "string",
  • "state": "UNKNOWN",
  • "start_time": "string",
  • "end_time": "string",
  • "tags": {
    }
}

RunRequest

workflow_params
object

OPTIONAL The workflow run parameterizations (JSON encoded), including input and output file locations. Either workflow_params or workflow_unified_params must be provided, workflow_unified_params takes precedence.

object

OPTIONAL Unified parameter format that can be converted to workflow-language-specific format. If provided, takes precedence over workflow_params. WES implementations should convert these to the appropriate native format for the specified workflow_type.

workflow_type
required
string

REQUIRED Workflow descriptor type, must be "CWL", "WDL", "Nextflow", or "Snakemake" currently (or another alternative supported by this WES instance, see service-info for supported types)

workflow_type_version
required
string

REQUIRED The workflow descriptor type version, must be one supported by this WES instance (see service-info for supported versions)

object

OPTIONAL Arbitrary key-value tags to associate with the workflow run for organization, tracking, or metadata purposes. Examples include experiment names, user identifiers, sample IDs, or project codes.

object
workflow_engine
string

OPTIONAL The workflow engine, must be one supported by this WES instance (see service-info for supported engines). Required if workflow_engine_version is provided.

workflow_engine_version
string

OPTIONAL The workflow engine version, must be one supported by this WES instance (see service-info for supported engine versions). If workflow_engine is provided, but workflow_engine_version is not, servers can make no assumptions with regard to the engine version the WES instance uses to process the request if that WES instance supports multiple versions of the requested engine.

workflow_url
required
string

REQUIRED The primary workflow document. When workflow_attachments is used to attach files, the workflow_url may be a relative path to one of the attachments that is the primary workflow to be executed.

Array of objects

OPTIONAL Additional workflow files required for execution (e.g., imported workflows, subworkflows, or dependencies). Each entry specifies both the source URL and target file path for precise file placement.

object

OPTIONAL Named credentials that can be referenced by input parameters that require authentication to access File or Directory resources. Each credential is identified by a unique key and can be referenced multiple times by different parameters to avoid duplicating large authentication tokens.

{
  • "workflow_params": { },
  • "workflow_unified_params": {
    },
  • "workflow_type": "string",
  • "workflow_type_version": "string",
  • "tags": {
    },
  • "workflow_engine_parameters": {
    },
  • "workflow_engine": "string",
  • "workflow_engine_version": "string",
  • "workflow_url": "string",
  • "additional_workflow_urls": [
    ],
  • "credentials": {
    }
}

RunLog

run_id
string

workflow run ID

object (RunRequest)

To execute a workflow, send a run request including all the details needed to begin downloading and executing a given workflow. If workflow_engine and workflow_engine_version are not provided, servers can use the most recent workflow_engine_version of workflow_engine that WES instance uses to process the request if supports for the requested workflow_type.

state
string (State)
Enum: "UNKNOWN" "QUEUED" "INITIALIZING" "RUNNING" "PAUSED" "COMPLETE" "EXECUTOR_ERROR" "SYSTEM_ERROR" "CANCELED" "CANCELING" "PREEMPTED"

State can take any of the following values:

  • UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing, for example, so that a missing field does not accidentally imply that the state is QUEUED.

  • QUEUED: The task is queued.

  • INITIALIZING: The task has been assigned to a worker and is currently preparing to run. For example, the worker may be turning on, downloading input files, etc.

  • RUNNING: The task is running. Input files are downloaded and the first Executor has been started.

  • PAUSED: The task is paused. An implementation may have the ability to pause a task, but this is not required.

  • COMPLETE: The task has completed running. Executors have exited without error and output files have been successfully uploaded.

  • EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally, this means that an Executor exited with a non-zero exit code.

  • SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor, for example an upload failed due to network issues, the worker's ran out of disk space, etc.

  • CANCELED: The task was canceled by the user.

  • CANCELING: The task was canceled by the user, and is in the process of stopping.

  • PREEMPTED: The task is stopped (preempted) by the system. The reasons for this would be tied to the specific system running the job. Generally, this means that the system reclaimed the compute capacity for reallocation.

object (Log)

Log and other info

task_logs_url
string

A reference to the complete url which may be used to obtain a paginated list of task logs for this workflow

Array of Log (object) or TaskLog (object) or null
Deprecated

The logs, and other key info like timing and exit code, for each step in the workflow run. This field is deprecated and the task_logs_url should be used to retrieve a paginated list of steps from the workflow run. This field will be removed in the next major version of the specification (2.0.0)

outputs
object

The outputs from the workflow run (legacy format). For outputs that require authentication to access (such as restricted files or directories), use the 'output_credentials' section of this response to obtain the necessary authentication credentials. The mapping between specific output files and credentials is implementation-specific for this legacy format - use 'structured_outputs' for explicit credential references.

object (WorkflowOutputs)

Structured workflow outputs with rich metadata and provenance information

object

Named credentials required to access workflow output files and directories. Each credential is identified by a unique key and can be referenced by multiple outputs via their 'credential_id' field. These credentials allow clients to authenticate and authorize access to restricted output resources.

{
  • "run_id": "string",
  • "request": {
    },
  • "state": "UNKNOWN",
  • "run_log": {
    },
  • "task_logs_url": "string",
  • "task_logs": [
    ],
  • "outputs": { },
  • "structured_outputs": {
    },
  • "output_credentials": {
    }
}

Log

name
string

The task or workflow name

cmd
Array of strings

The command line that was executed

start_time
string

When the command started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"

end_time
string

When the command stopped executing (completed, failed, or cancelled), in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"

stdout
string

A URL to retrieve standard output logs of the workflow run or task. This URL may change between status requests, or may not be available until the task or workflow has finished execution. Should be available using the same credentials used to access the WES endpoint.

stderr
string

A URL to retrieve standard error logs of the workflow run or task. This URL may change between status requests, or may not be available until the task or workflow has finished execution. Should be available using the same credentials used to access the WES endpoint.

exit_code
integer <int32>

Exit code of the program

system_logs
Array of strings

System logs are any logs the system decides are relevant, which are not tied directly to a workflow. Content is implementation specific: format, size, etc.

System logs may be collected here to provide convenient access.

For example, the system may include an error message that caused a SYSTEM_ERROR state (e.g. disk is full), etc.

{
  • "name": "string",
  • "cmd": [
    ],
  • "start_time": "string",
  • "end_time": "string",
  • "stdout": "string",
  • "stderr": "string",
  • "exit_code": 0,
  • "system_logs": [
    ]
}

TaskLog

name
required
string

The task or workflow name

cmd
Array of strings

The command line that was executed

start_time
string

When the command started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"

end_time
string

When the command stopped executing (completed, failed, or cancelled), in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ"

stdout
string

A URL to retrieve standard output logs of the workflow run or task. This URL may change between status requests, or may not be available until the task or workflow has finished execution. Should be available using the same credentials used to access the WES endpoint.

stderr
string

A URL to retrieve standard error logs of the workflow run or task. This URL may change between status requests, or may not be available until the task or workflow has finished execution. Should be available using the same credentials used to access the WES endpoint.

exit_code
integer <int32>

Exit code of the program

system_logs
Array of strings

System logs are any logs the system decides are relevant, which are not tied directly to a workflow. Content is implementation specific: format, size, etc.

System logs may be collected here to provide convenient access.

For example, the system may include an error message that caused a SYSTEM_ERROR state (e.g. disk is full), etc.

id
required
string

A unique identifier which may be used to reference the task

tes_uri
string

An optional URL pointing to an extended task definition defined by a TES api

{
  • "name": "string",
  • "cmd": [
    ],
  • "start_time": "string",
  • "end_time": "string",
  • "stdout": "string",
  • "stderr": "string",
  • "exit_code": 0,
  • "system_logs": [
    ],
  • "id": "string",
  • "tes_uri": "string"
}

TaskListResponse

Array of objects (TaskLog)

The logs, and other key info like timing and exit code, for each step in the workflow run.

next_page_token
string

A token which may be supplied as page_token in workflow run task list request to get the next page of results. An empty string indicates there are no more items to return.

{
  • "task_logs": [
    ],
  • "next_page_token": "string"
}

DefaultWorkflowEngineParameter

name
string

The name of the parameter

type
string

Describes the type of the parameter, e.g. float.

default_value
string

The stringified version of the default parameter. e.g. "2.45".

{
  • "name": "string",
  • "type": "string",
  • "default_value": "string"
}

WorkflowTypeVersion

workflow_type_version
Array of strings

an array of one or more acceptable type and versions for the workflow_type. Use the convention <workflow_type>_<version> to encode this array for clarity. For example, a WES service supporting CWL 1.0 and WDL 1.1 would encode this as ["CWL_1.0", "WDL_1.1"].

{
  • "workflow_type_version": [
    ]
}

WorkflowEngineVersion

workflow_engine_version
Array of strings

An array of one or more acceptable engines versions for the workflow_engine. Since a server may support multiple engines and version, the recommendation is to encode this array as <workflow_engine>_<version> for clarity.

{
  • "workflow_engine_version": [
    ]
}

WorkflowOutputs

version
string
Default: "1.0"

Version of the structured outputs format

object

Named workflow outputs with structured metadata

{
  • "version": "1.0",
  • "outputs": {
    }
}

OutputObject

class
required
string
Enum: "File" "Directory" "Array" "String" "Integer" "Float" "Boolean"

Type of the output object

value
required
any

Output value (type depends on class field)

location
string

Absolute path or URL to the output file/directory (for File/Directory class)

basename
string

Filename without directory path (for File/Directory class)

size
integer <int64>

Size in bytes (for File/Directory class)

checksum
string

File integrity hash in format 'algorithm:hash' (e.g., 'sha256:abc123...')

format
string

MIME type or format identifier (e.g., EDAM ontology reference)

items
Array of objects (OutputObject)

Array elements (for Array class)

object

Additional metadata about the output

secondary_files
Array of objects (OutputObject)

Associated files (e.g., index files, companion files)

contents
string

File contents for small files (≤64 KiB)

credential_id
string

Reference to a credential ID defined in the 'output_credentials' section of the RunLog response. This credential is required to authenticate and authorize access to this File or Directory output resource.

{
  • "class": "File",
  • "value": null,
  • "location": "string",
  • "basename": "string",
  • "size": 0,
  • "checksum": "string",
  • "format": "string",
  • "items": [
    ],
  • "metadata": {
    },
  • "secondary_files": [
    ],
  • "contents": "string",
  • "credential_id": "string"
}