Runs REST API¶
This document provides a comprehensive overview of the Runs REST API for Wherobots.
For a detailed tutorial about using the WherobotsRunOperator
constructor, see WherobotsRunOperator.
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: POST http://api.cloud.wherobots.com/runs
Request body schema¶
The following parameters are associated with the Create run endpoint.
Parameter | Type | Required or Optional | Parameter description | Rules for accepted values |
---|---|---|---|---|
runtime |
enum |
Optional | Wherobots runtime. | Runtime.TINY ,Runtime.SMALL , Runtime.MEDIUM , Runtime.LARGE , Runtime.X_LARGE , Runtime.XX_LARGE , Runtime.XXXX_LARGE , Runtime.MEDIUM_HIMEM , Runtime.LARGE_HIMEM , Runtime.X_LARGE_HIMEM , Runtime.XX_LARGE_HIMEM , Runtime.XXXX_LARGE_HIMEM , Runtime.TINY_A10_GPU , Runtime.SMALL_A10_GPU , Runtime.MEDIUM_A10_GPU You can see the runtimes available to your Organization in the Start a Notebook dropdown in Wherobots Cloud. |
name |
str |
Optional | The user-assigned name of the run. If not specified, a default name will be generated. | [8, 255] character matches ^[a-zA-Z0-9_\-\.]+$ |
runPython |
dict |
Optional | Used to run a Python file. | An S3 path to Python file. This file can be stored in Wherobots' Managed Storage. Takes the following keys: uri: (str ) and args: (list[str] ). You can use either run_python or run_jar , not both. |
runJar |
dict |
Optional | Used to run a JAR file. | An S3 path to Java Archive (JAR) file. This file can be stored in Wherobots' Managed Storage. Takes the following keys: uri: (str ), args: (list[str] ), mainClass: (str ). You can use either run_python or run_jar , not both. |
timeoutSeconds |
int |
Optional | The timeout of the run. Defaults to 3600 . |
If the value is greater than Max Workload Alive Hours multiplied by 3600 , the API server will change this value to the maximum value allowed. |
environment |
dict |
Optional | The model for runtime environment configs, include spark cluster configs, dependencies. Defaults to {} . See Environment keys. |
Environment keys¶
Environment parameter | Type | Required or Optional | Parameter description | Rules for accepted Values |
---|---|---|---|---|
sparkConfigs |
dict{str:str} |
Optional | ||
dependencies |
list |
Optional | ||
sparkDriverDiskGB |
int |
Optional | The driver disk size of the Spark cluster. | |
sparkExecutorDiskGB: |
int |
Optional | The executor disk size of the Spark cluster. | |
sparkConfigs |
dict{str:str} |
Optional | The user specified spark configs. | |
dependencies |
list[dict[str, Any]] |
Optional | Indicates the 3rd party dependencies need to add to the runtime. Required if adding sparkConfigs. |
Must be an array (list) of objects (dictionaries). Each object must represent either a Python Package Index or a File Dependency. |
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’ Managed Storage.
{
"runtime": 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’ Managed Storage.
{
"runtime": 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 accepted values |
---|---|---|---|
sourceType |
str |
Enum for the source type of dependency | Valid values: PYPI or FILE |
filePath |
str |
The file path to the dependency file. | Must be a valid file path accessible within the runtime environment. The file extension must be one of the following: .jar , .whl , or .zip . |
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 | Parameter Type | Details | Rules for Accepted Values |
---|---|---|---|
sourceType |
str |
Indicates the source type of the dependency. | Must be set to PYPI . |
libraryName |
str |
The name of the Python library to be installed from PyPI. | Must be a valid PyPI package name (e.g., "pandas" , "requests" ). |
libraryVersion |
str |
The specific version of the PyPI library to install. | Must be a valid version 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 Accepted Values |
---|---|---|---|
sourceType |
str |
Indicates the source type of the dependency. | Must be set to FILE . |
filePath |
str |
The file path to the dependency file. | Must be a valid file path accessible within the runtime environment. The file extension must be one of: .jar , .whl , or .zip . |
Dependencies example¶
{
"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.
{
"runtime": 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.
{
"runtime": 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.
{
"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": [
{
"id": "string",
"createTime": "2024-09-25T02:23:34.646Z",
"updateTime": "2024-09-25T02:23:34.646Z",
"name": "string",
"organizationId": "string",
"policies": [
{
"id": "string",
"createTime": "2024-09-25T02:23:34.646Z",
"updateTime": "2024-09-25T02:23:34.646Z",
"provider": "WHEROBOTS",
"locator": "string",
"action": "string",
"effect": "ALLOW"
}
]
}
]
},
"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": 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.
Route: GET http://api.cloud.wherobots.com/runs/<RUN_ID>
Successful response example¶
{
"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": [
{
"id": "string",
"createTime": "2024-09-25T18:23:01.538Z",
"updateTime": "2024-09-25T18:23:01.538Z",
"name": "string",
"organizationId": "string",
"policies": [
{
"id": "string",
"createTime": "2024-09-25T18:23:01.538Z",
"updateTime": "2024-09-25T18:23:01.538Z",
"provider": "WHEROBOTS",
"locator": "string",
"action": "string",
"effect": "ALLOW"
}
]
}
]
},
"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": 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.
Route: 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 to check a Job Run's status.
Get Run Logs¶
The Get Run Logs 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.
Route: GET http://api.cloud.wherobots.com/runs/<RUN_ID>/logs
Request body schema¶
Parameter | Type | Required or Optional | Parameter description | Rules for 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¶
{
"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: GET http://api.cloud.wherobots.com/runs
Request body schema¶
Parameter | Type | Required or Optional | Parameter description | Rules for accepted values |
---|---|---|---|---|
name |
str |
Optional | The name of the job. | Max length: 255 pattern: ^[a-zA-Z0-9_\-\.]*\*?[a-zA-Z0-9_\-\.]*$ |
created_after |
str |
Optional | The retrieved logs will have occurred after this specified date and time. | $YYYY-MM-DD-Hours:Minutes:Seconds UTC |
status |
array[str] |
Optional | Filter the runs with the condition. | Valid values: PENDING, RUNNING, FAILED, COMPLETED, CANCELLED |
region |
str |
Optional | The compute region where the Run was created. | |
cursor |
str |
Optional | This parameter indicates the position of the last item on the previous page. | |
size |
int |
Optional | This parameter indicates the maximum number of items fetched for the current page. | Defaults to 50 . Maximum: 100 Minimum: 0 |
Successful response example¶
{
"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": [
{
"id": "string",
"createTime": "2024-09-25T20:47:25.280Z",
"updateTime": "2024-09-25T20:47:25.280Z",
"name": "string",
"organizationId": "string",
"policies": [
{
"id": "string",
"createTime": "2024-09-25T20:47:25.280Z",
"updateTime": "2024-09-25T20:47:25.280Z",
"provider": "WHEROBOTS",
"locator": "string",
"action": "string",
"effect": "ALLOW"
}
]
}
]
},
"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": 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"
}