---
updatedAt: 2025-11-10T23:06:34.000Z
agentTools:
  projectIndex: https://docs.cavatica.org/llms.txt
---

# Run a workflow

This call runs (executes) a workflow and returns the run ID which you can use to monitor its progress (see [Get details of a workflow run](https://docs.cavatica.org/docs/get-details-of-a-workflow-run)).

```text Path
https://cavatica-ga4gh-api.sbgenomics.com/ga4gh/wes/v1/runs
```

## Request

### Example request

```http
POST /ga4gh/wes/v1/runs HTTP/1.1
Host: cavatica-ga4gh-api.sbgenomics.com
X-SBG-Auth-Token: 55e9691c111146bd384c5ec40a9f97fb1
```
```curl cURL
curl --location --request POST 'https://cavatica-ga4gh-api.sbgenomics.com/ga4gh/wes/v1/runs' \
--header 'X-SBG-Auth-Token: 55e9691c111146d384c5ec40a9f97fc0' \
--header 'Cookie: language=en' \
--form 'workflow_params={"project": "rfranklin/my-project", "use_interruptible_instances": true, "inputs": {"input_bam": {"class": "File", "path": "drs://cavatica-ga4gh-api.sbgenomics.com/5f7b09a2e4b0e67085ff9386"}}};type=application/json'  \
--form 'workflow_type=CWL' \
--form 'tags={}' \
--form 'workflow_engine_parameters={}' \
--form 'workflow_url=sbg://rfranklin/my-project/tool/0'
```

### Header Fields

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Name
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `X-SBG-Auth-Token`
        *required*
      </td>

      <td>
        Your [authentication token](https://docs.cavatica.org/docs/get-your-authentication-token).
      </td>
    </tr>
  </tbody>
</Table>

### Request body

> 📘 When running a new workflow via WES on CAVATICA, you need to specify the target [project](https://docs.cavatica.org/docs/projects-on-cavatica) using the `project` parameter. See details below.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Name
      </th>

      <th>
        Data type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `workflow_params`
        *required*
      </td>

      <td>
        object
      </td>

      <td>
        Specify the name of the project using the `project` (*required*) parameter , e.g. `"project": "rfranklin/my-project"`.

        You can also use this parameter to specify the input files:

        * The path to the files can be specified either as a platform-local DRS URI or file ID.

        - *Option to specify files via an external DRS URI is coming soon.*
      </td>
    </tr>

    <tr>
      <td>
        `workflow_type`\
        *required*
      </td>

      <td>
        string
      </td>

      <td>
        The type of workflow language submitted which is [supported by this WES instance](https://docs.cavatica.org/docs/get-service-information).
      </td>
    </tr>

    <tr>
      <td>
        `workflow_type_version`\
        *required*
      </td>

      <td>
        string
      </td>

      <td>
        The version of the workflow language submitted which is [supported by this WES instance](https://docs.cavatica.org/docs/get-service-information).
      </td>
    </tr>

    <tr>
      <td>
        `tags`
      </td>

      <td>
        string
      </td>

      <td>
        Specify tags.
      </td>
    </tr>

    <tr>
      <td>
        `workflow_url`\
        *required*
      </td>

      <td>
        string
      </td>

      <td>
        This parameter is used for specifying the location of the App, which can be any of the following:

        * **App in your project** - specify the URL to the app, e.g. `sbg://admin/sbg-public-data/topmed-alignment`
        * **App in the Dockstore** - specify the URL to your app in the Dockstore, using the standard HTTP or TRS format
        * **App uploaded via`workflow_attachment` **- specify the relative path to the appropriate attachment, e.g. `#/workflow_attachment/0`
      </td>
    </tr>

    <tr>
      <td>
        `workflow_attachment`
      </td>

      <td>
        Array of strings &lt;binary&gt;
      </td>

      <td>
        The `workflow_attachment` array may be used to upload the App needed to execute the workflow.
      </td>
    </tr>
  </tbody>
</Table>

## Example request body

```json
{
  "workflow_params": {
    "project": "rfranklin/my-project",
    "inputs": {
      "input_list": [
        {
          "path": "drs://cavatica-ga4gh-api.sbgenomics.com/5a9d49c04f0c482419bb5f8e",
          "name": "C835.HCC1143.2.converted.realigned.base_recalibrated.bam",
          "class": "File"
        }
      ],
      "Reference_Genome_FASTA": {
        "path": "drs://cavatica-ga4gh-api.sbgenomics.com/5a9d49d54f0c482419bb5f98",
        "name": "Homo_sapiens_assembly38.fasta",
        "class": "File"
      }
    }
  },
  "workflow_type": "CWL",
  "workflow_type_version": "v1.0",
  "workflow_url": "sbg://rfranklin/my-project/alignment-metrics-qc/0"
}
```

## Response

[See a list of response codes that may be contained in the body of the response.](https://docs.cavatica.org/docs/api-status-codes)

### Response body

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Name
      </th>

      <th>
        Data type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `run_id`
      </td>

      <td>
        string
      </td>

      <td>
        Workflow run ID
      </td>
    </tr>
  </tbody>
</Table>

### Example response body

```json
{
  "run_id": "103e7bc8-224e-4c97-9664-6f98a2cb7e2d"
}
```