> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs REST API

This document provides a comprehensive overview of the Wherobots Runs REST API, a programming
interface for managing job runs.

If you are orchestrating jobs with [Apache Airflow](https://airflow.apache.org/), an open-source platform for scheduling and managing
complex data workflows, we recommend using the `WherobotsRunOperator`. For more information on this constructor, see the
documentation for the [`WherobotsRunOperator`](/develop/run-operator/)

<Tip>
  **Track your Job Runs in Wherobots Cloud**

  The [**Job Runs**](https://cloud.wherobots.com/job-runs) detail page in Wherobots Cloud provides insights into job progress, resource consumption, execution timelines, and configuration settings.
</Tip>

## Before you start

Before using the Runs REST API, ensure that you have the following required resources:

* An account within a Professional or Enterprise Edition Organization. For more information, see [Create a Wherobots Account](/get-started/wherobots-cloud/create-account/).
* A Wherobots API key. For more information on creating and accessing API keys see [API Keys](/get-started/wherobots-cloud/api-keys/).

## HTTP Request

```bash title="Example" linenums="1" hl_lines="4" theme={"system"}
curl -X 'POST' \
 'https://api.cloud.wherobots.com/runs' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR-API-KEY' \
  -H 'Content-Type: application/json' \
  -d 'input json'
```

In **line 4**, replace `YOUR-API-KEY` with a Wherobots API key.

## Response codes

The following table details a comprehensive listing of response codes encountered during a run's execution.

| Response code | Definition            |
| :------------ | :-------------------- |
| 200           | Successful response   |
| 400           | Bad Request           |
| 401           | Unauthorized          |
| 403           | Forbidden             |
| 404           | Not found             |
| 422           | Validation Error      |
| 500           | Internal Server Error |

## Create Run

The Create Run endpoint allows you to create a new run in Wherobots, specifying the runtime, name, and optional parameters for running Python or JAR files.

**Route:** `#!json POST http://api.cloud.wherobots.com/runs?region=<region>`

### Request parameters

The following parameters are associated with the Create run endpoint.

**Query parameters:**

| Parameter | Type  | Required or Optional | Parameter description                           | Rules for<br />Accepted Values                                                                                 |
| :-------- | :---- | :------------------- | :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
| `region`  | `str` | Required             | Compute region where the Run should be created. | See [Cloud and Cloud Region Availability](/availability#cloud-and-cloud-region-availability) for valid values. |

**Request body schema:**

<table id="wherobotsParamsTable">
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Type</th>
      <th>Required or Optional</th>
      <th>Parameter<br />description</th>
      <th>Rules for<br />Accepted Values</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>runtime</code></td>
      <td><code>str</code></td>
      <td>Required</td>
      <td>Wherobots runtime.</td>

      <td>
        <code>micro</code>, <code>tiny</code>, <code>small</code>, <code>medium</code>, <code>large</code>, <code>x-large</code>, <code>2x-large</code>, <code>4x-large</code>, <code>medium-himem</code>, <code>large-himem</code>, <code>x-large-himem</code>, <code>2x-large-himem</code>, <code>4x-large-himem</code>
        <br /><br />You can see the runtimes available to your Organization in the <strong>Start a Notebook</strong> dropdown in <a href="https://cloud.wherobots.com/">Wherobots Cloud</a>.
      </td>
    </tr>

    <tr>
      <td><code>name</code></td>
      <td><code>str</code></td>
      <td>Required</td>
      <td>The user-assigned name of the run.</td>
      <td>8 to 255 character matching <code>^\[a-zA-Z0-9\_-.]+\$</code></td>
    </tr>

    <tr>
      <td><code>version</code></td>
      <td><code>str</code></td>
      <td>Optional</td>
      <td>String literals that map to a specific Wherobots version.<br /><br />
      <code>"latest"</code> refers to the most recent, stable production version available.<br /><br /><code>"preview"</code> refers to the most recent pre-release or testing version available.<br /><br />Defaults to <code>"latest"</code><br /><br />You can find additional available versions in <a href="/develop/notebook-management/environment-presets">Environment Presets</a>.</td>
      <td><code>latest</code>, <code>preview</code></td>
    </tr>

    <tr>
      <td><code>runPython</code></td>
      <td><code>dict</code></td>
      <td>Optional</td>

      <td>
        Used to run a Python file.
      </td>

      <td>
        An S3 path to Python file. <a href="/develop/storage-management/storage/#wherobots-managed-storage">Wherobots Managed Storage</a> and <a href="/develop/storage-management/s3-storage-integration/">Storage Integration</a> S3 paths are supported.
        <br /><br />Takes the following keys: <code>uri:str</code> specifying the file path to your script and <code>args:list\[str]</code> an optional list of arguments to pass to the script.
        <br /><br />You can use either <code>runPython</code> or <code>runJar</code>, not both.
      </td>
    </tr>

    <tr>
      <td><code>runJar</code></td>
      <td><code>dict</code></td>
      <td>Optional</td>

      <td>
        Used to run a JAR file.
      </td>

      <td>
        An S3 path to Java Archive (JAR) file. <a href="/develop/storage-management/storage/#wherobots-managed-storage">Wherobots Managed Storage</a> and <a href="/develop/storage-management/s3-storage-integration/">Storage Integration</a> S3 paths are supported.
        <br /><br />Takes the following keys: <code>uri:str</code> specifying the file path to your script and <code>args:list\[str]</code> an optional list of arguments to pass to the script.
        <br /><br />You can use either <code>runPython</code> or <code>runJar</code>, not both.
      </td>
    </tr>

    <tr>
      <td><code>timeoutSeconds</code></td>
      <td><code>int</code></td>
      <td>Optional</td>
      <td>The timeout of the run. Defaults to <code>3600</code>.</td>
      <td>If the value is greater than Max Workload Alive Hours multiplied by <code>3600</code>, the API server will change this value to the maximum value allowed.</td>
    </tr>

    <tr>
      <td><code>environment</code></td>
      <td><code>dict</code></td>
      <td>Optional</td>
      <td>The model for runtime environment configs, include spark cluster configs, dependencies. Defaults to <code>{}</code>.</td>
      <td>See <a href="/reference/runs/#environment-keys">Environment keys</a>.</td>
    </tr>
  </tbody>
</table>

#### Environment keys

<table id="environmentParamsTable">
  <thead>
    <tr>
      <th>Environment<br />parameter</th>
      <th>Type</th>
      <th>Required or Optional</th>
      <th>Parameter description</th>
      <th>Rules for<br />Accepted Values</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sparkDriverDiskGB</code></td>
      <td><code>int</code></td>
      <td>Optional</td>
      <td>The driver disk size of the Spark cluster.</td>

      <td />
    </tr>

    <tr>
      <td><code>sparkExecutorDiskGB</code></td>
      <td><code>int</code></td>
      <td>Optional</td>
      <td>The executor disk size of the Spark cluster.</td>

      <td />
    </tr>

    <tr>
      <td><code>sparkConfigs</code></td>
      <td><code>`dict{str:str}`</code></td>
      <td>Optional</td>
      <td>The user specified spark configs.</td>

      <td />
    </tr>

    <tr>
      <td><code>dependencies</code></td>
      <td><code>list\[dict\[str, Any]]</code></td>
      <td>Optional</td>
      <td>Indicates the 3rd party dependencies need to<br /> add to the runtime. Required if adding sparkConfigs.</td>
      <td>Must be an array (list) of objects (dictionaries). Each object must represent either a Python Package Index or a File Dependency.</td>
    </tr>
  </tbody>
</table>

#### Run Python

The following code snippet details a Job Run request that runs a Python file. In practice,
replace `S3-PATH-TO-FILE` with the S3 path of your Python file in Wherobots. [Wherobots Managed Storage](/develop/storage-management/storage/#wherobots-managed-storage) and [Storage Integration](/develop/storage-management/s3-storage-integration/) S3 paths are supported.

<Note>
  `args` returns an empty list, `[]`, if `uri: "YOUR-S3-PATH"` is used in the `runPython` request without `args: list[str]`.
</Note>

```json theme={"system"}
{
  "runtime": "tiny",
  "name": "test_run",
  "runPython": {
    "uri": "S3-PATH-TO-FILE"
  },
  "timeoutSeconds": 3600
}
```

#### Run JAR

The following code snippet details a Jobs run request that runs a JAR file. In practice,
replace `S3-PATH-TO-FILE` with the S3 path of your JAR file in Wherobots. [Wherobots Managed Storage](/develop/storage-management/storage/#wherobots-managed-storage) and [Storage Integration](/develop/storage-management/s3-storage-integration/) S3 paths are supported.

```json theme={"system"}
{
  "runtime": "tiny",
  "name": "test_run",
  "runJar": {
    "uri": "S3-PATH-TO-FILE",
    "mainClass": "main.class"
  },
  "timeoutSeconds": 3600
}
```

#### Dependencies

The following details information on the third-party dependencies that can be added to the runtime environment.

| Parameter    | Type  | Details                                    | Rules for<br />Accepted Values                                                                                                                                                 |
| :----------- | :---- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceType` | `str` | Enum for the source type<br /> dependency. | Valid values: `PYPI` or `FILE`                                                                                                                                                 |
| `filePath`   | `str` | File path to dependency file.              | Must be a valid file path accessible<br />within the runtime environment.<br /> The file extension must<br />be one of the following:<br />`.jar`, `.whl`, `.zip`, or `.json`. |

##### Python Package Index (PyPI) dependency object

Python Package Index dependency objects are used to represent third-party Python packages that need to be added to the runtime environment.

| Parameter        | Type  | Details                                                         | Rules for<br />Accepted Values                                                |
| :--------------- | :---- | :-------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| `sourceType`     | `str` | Source type of the dependency.                                  | Must be set to `PYPI`.                                                        |
| `libraryName`    | `str` | Name of the Python<br />library to be<br />installed from PyPI. | Must be a valid<br />PyPI package name<br />(e.g., `"pandas"`, `"requests"`). |
| `libraryVersion` | `str` | The specific version of<br />the PyPI library to install.       | Must be a valid version<br />specifier compatible with PyPI.                  |

##### File dependency object

The file dependency object allows you to specify a file to be added to the runtime environment.

| Parameter    | Parameter Type | Details                                           | Rules for<br />Accepted Values                                                                                                                                                                                                                                                                                                                                       |
| :----------- | :------------- | :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceType` | `str`          | Indicates the source<br />type of the dependency. | Must be set to `FILE`.                                                                                                                                                                                                                                                                                                                                               |
| `filePath`   | `str`          | The file path to<br />the dependency file.        | Must be a valid file<br />path accessible<br />within the runtime environment.<br />The file extension must<br />be one of: `.jar`, `.whl`, `.zip`, or `.json`.<br /><br />JSON files can be used to place a<br />configuration file at a predetermined<br />file-system location on all nodes<br />of the compute cluster<br />(`/opt/wherobots/<file name>.json`). |

##### Dependencies example

```json theme={"system"}
{
  "dependencies": [
    {
      "sourceType": "PYPI",
      "libraryName": "pandas",
      "libraryVersion": "1.5.3"
    },
    {
      "sourceType": "FILE",
      "filePath": "/path/to/my_custom_library.jar"
    }
  ]
}
```

### Request example

This is an example of a Jobs run request that runs a Python file.

```json theme={"system"}
POST /runs?request=aws-us-west-2

{
  "runtime": "tiny",
  "name": "string",
  "runPython": {
    "uri": "string",
    "args": []
  },
  "timeoutSeconds": 3600,
  "environment": {
    "sparkConfigs": {},
    "dependencies": []
  }
}
```

This is an example of a Jobs run request that runs a JAR file.

```json theme={"system"}
POST /runs?region=aws-us-west-2

{
  "runtime": "tiny",
  "name": "string",
  "runJar": {
    "uri": "string",
    "args": [],
    "mainClass": "string"
  },
  "timeoutSeconds": 3600,
  "environment": {
    "sparkConfigs": {},
    "dependencies": []
  }
}
```

### Successful response example

The following is an example of a successful response. A successful response returns the `200` status code.

```json theme={"system"}
{
  "id": "string",
  "createTime": "2024-09-25T02:23:34.646Z",
  "updateTime": "2024-09-25T02:23:34.646Z",
  "name": "string",
  "status": "PENDING",
  "triggeredBy": {
    "id": "string",
    "createTime": "2024-09-25T02:23:34.646Z",
    "updateTime": "2024-09-25T02:23:34.646Z",
    "email": "string",
    "name": "string",
    "roles": [ ... ]
  },
  "startTime": "2024-09-25T02:23:34.646Z",
  "completeTime": "2024-09-25T02:23:34.646Z",
  "kubeApp": {
    "id": "string",
    "createTime": "2024-09-25T02:23:34.646Z",
    "updateTime": "2024-09-25T02:23:34.646Z",
    "instanceId": "string",
    "appType": "string",
    "status": "PENDING",
    "createdById": "string",
    "apiPayload": {},
    "appMeta": {},
    "events": [],
    "message": "string"
  },
  "payload": {
    "runtime": "tiny",
    "name": "string",
    "runPython": {
      "uri": "string",
      "args": []
    },
    "runJar": {
      "uri": "string",
      "args": [],
      "mainClass": "string"
    },
    "timeoutSeconds": 3600,
    "environment": {
      "sparkConfigs": {},
      "dependencies": []
    }
  }
}
```

## Get Run

The Get Run endpoint allows you to get the details of a Wherobots Job Run.
In practice, replace `<RUN_ID>`, with the ID of an existing run, which can be
found by querying [List Runs](/reference/runs/#list-runs).

**Route:** `#!json GET http://api.cloud.wherobots.com/runs/<RUN_ID>`

### Successful response example

```json theme={"system"}
{
  "id": "string",
  "createTime": "2024-09-25T18:23:01.538Z",
  "updateTime": "2024-09-25T18:23:01.538Z",
  "name": "string",
  "status": "PENDING",
  "triggeredBy": {
    "id": "string",
    "createTime": "2024-09-25T18:23:01.538Z",
    "updateTime": "2024-09-25T18:23:01.538Z",
    "email": "string",
    "name": "string",
    "roles": [ ... ]
  },
  "startTime": "2024-09-25T18:23:01.538Z",
  "completeTime": "2024-09-25T18:23:01.538Z",
  "kubeApp": {
    "id": "string",
    "createTime": "2024-09-25T18:23:01.538Z",
    "updateTime": "2024-09-25T18:23:01.538Z",
    "instanceId": "string",
    "appType": "string",
    "status": "PENDING",
    "createdById": "string",
    "apiPayload": {},
    "appMeta": {},
    "events": [],
    "message": "string"
  },
  "payload": {
    "runtime": "tiny",
    "name": "string",
    "runPython": {
      "uri": "string",
      "args": []
    },
    "runJar": {
      "uri": "string",
      "args": [],
      "mainClass": "string"
    },
    "timeoutSeconds": 3600,
    "environment": {
      "sparkConfigs": {},
      "dependencies": []
    }
  }
}
```

## Cancel Run

The Cancel Run endpoint allows you to cancel a Wherobots Job Run. In practice,
replace `<RUN_ID>`, with the ID of an existing run, which can be found
by querying [List Runs](/reference/runs/#list-runs).

**Route:** `#!json POST http://api.cloud.wherobots.com/runs/<RUN_ID>/cancel`

### Successful response

Returns `200` when request cancels successfully.
It can take a minute before the status changes to
`CANCELLED`. Query [Get Run](/reference/runs/#get-run) to check a Job Run's status.

## Get Run Logs

The Get Run Logs endpoint allows you to see the logs for a Wherobots Job Run.
In practice, replace `<RUN_ID>`, with the ID of an existing run, which can be found
by querying [List Runs](/reference/runs/#list-runs).

**Route:** `#!json GET http://api.cloud.wherobots.com/runs/<RUN_ID>/logs`

### Request query parameters schema

Example: `http://api.cloud.wherobots.com/runs/<RUN_ID>/logs?cursor=0&size=100`

| Parameter | Type  | Required or Optional | Parameter description                                                              | Rules for<br />Accepted Values |
| :-------- | :---- | :------------------- | :--------------------------------------------------------------------------------- | :----------------------------- |
| `size`    | `int` | Optional             | This parameter indicates the position of the last item on the previous page.       | Defaults to `100`              |
| `cursor`  | `int` | Optional             | This parameter indicates the maximum number of items fetched for the current page. | Defaults to `0`                |

### Successful response example

```json theme={"system"}
{
  "items": [
    {
      "timestamp": 0,
      "raw": "string"
    }
  ],
  "current_page": 0,
  "next_page": 0
}
```

## List Runs

The List Runs endpoint allows you to see all of the Wherobots runs in your Organization.

**Route:** `#!json GET http://api.cloud.wherobots.com/runs`

### Request parameters

The following query parameters can be provided to refine the search:

| Parameter       | Type         | Required<br />or<br />Optional | Parameter<br />Description                                                             | Rules for<br />Accepted<br />Values                                                                                                                         |
| :-------------- | :----------- | :----------------------------- | :------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region`        | `str`        | Optional                       | Filter the runs by the compute region in which they executed.                          | See [Cloud and Cloud Region Availability](/availability#cloud-and-cloud-region-availability) for valid values.                                              |
| `name`          | `str`        | Optional                       | Filter the runs by name pattern.                                                       | Max length: 255<br /> Can contain any number<br />of letters, numbers,<br />underscores, hyphens, or<br />periods, and can<br /> include a single asterisk. |
| `created_after` | `str`        | Optional                       | Filter for runs that have been created after this date.                                | \$YYYY-MM-DD<br />-Hours:Minutes:Seconds UTC                                                                                                                |
| `status`        | `array[str]` | Optional                       | Filter the runs by status.                                                             | Valid values:<br />`PENDING`, `RUNNING`,<br />`FAILED`, `COMPLETED`,<br /> `CANCELLED`                                                                      |
| `cursor`        | `str`        | Optional                       | Indicates the position<br />of the last item<br />on the previous page for pagination. |                                                                                                                                                             |
| `size`          | `int`        | Optional                       | Indicates the maximum<br />number of items<br />fetched for the<br />current page.     | Defaults to `50`.<br />Maximum: `100`<br />Minimum: `0`                                                                                                     |

### Successful response example

```json theme={"system"}
{
  "items": [
    {
      "id": "string",
      "createTime": "2024-09-25T20:47:25.280Z",
      "updateTime": "2024-09-25T20:47:25.280Z",
      "name": "string",
      "status": "PENDING",
      "triggeredBy": {
        "id": "string",
        "createTime": "2024-09-25T20:47:25.280Z",
        "updateTime": "2024-09-25T20:47:25.280Z",
        "email": "string",
        "name": "string",
        "roles": [ ... ]
      },
      "startTime": "2024-09-25T20:47:25.280Z",
      "completeTime": "2024-09-25T20:47:25.280Z",
      "kubeApp": {
        "id": "string",
        "createTime": "2024-09-25T20:47:25.280Z",
        "updateTime": "2024-09-25T20:47:25.280Z",
        "instanceId": "string",
        "appType": "string",
        "status": "PENDING",
        "createdById": "string",
        "apiPayload": {},
        "appMeta": {},
        "events": [],
        "message": "string"
      },
      "payload": {
        "runtime": "tiny",
        "name": "string",
        "runPython": {
          "uri": "string",
          "args": []
        },
        "timeoutSeconds": 3600,
        "environment": {
          "sparkConfigs": {},
          "dependencies": []
        }
      }
    }
  ],
  "total": 0,
  "current_page": "string",
  "current_page_backwards": "string",
  "previous_page": "string",
  "next_page": "string"
}
```