> ## 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.

# Wherobots Cloud Python SDK

> Submit job runs, run tasks, and manage files in Wherobots Cloud from Python with the wherobots-python-sdk package.

The Wherobots Cloud Python SDK is a Python client for the Wherobots Cloud REST APIs. Use it to submit and monitor job runs, run tasks such as RasterFlow inference, and manage your files in [My Files](https://docs.wherobots.com/develop/storage-management/file-explorer.md). It requires Python 3.11 or later.

This SDK manages Wherobots Cloud resources from any Python environment. It is a different package from the [WherobotsDB Python API](https://docs.wherobots.com/reference/wherobots-db/python/overview.md), which runs spatial queries inside a runtime, and from the [RasterFlow client](https://docs.wherobots.com/reference/rasterflow/client.md).

```bash theme={"system"}
pip install wherobots-python-sdk
```

## Authenticate

The SDK authenticates with a Wherobots [API key](https://docs.wherobots.com/get-started/wherobots-cloud/api-keys.md). Set the `WHEROBOTS_API_KEY` environment variable, or pass `api_key` to `Wherobots` or `WherobotsJob`. In Wherobots notebooks and job runs, the SDK authenticates automatically, so you don't need an API key there.

## Submit a job run

`WherobotsJob` submits a Python script or JAR as a job run. Pass a local file, which the SDK uploads for you, or an `s3://` URI.

```python theme={"system"}
from wherobots import WherobotsJob

with WherobotsJob(script="my_analysis.py", name="my-analysis-001") as job:
    job.submit()
    status = job.wait_for_completion()
print(status)
```

`wait_for_completion` prints the job run's logs until it finishes, then returns its final status. The `with` block closes the job's API connection when it ends.

## Manage files and tasks

The `Wherobots` client holds one API connection for your files, tasks, and task runs. Close it, or use it in a `with` block, to release the connection. My Files is separate in each region, so set `region` or the `WHEROBOTS_REGION` environment variable to work with files.

```python theme={"system"}
from wherobots import Wherobots

with Wherobots(region="aws-us-west-2") as wb:
    for entry in wb.files.my_files.list_directory():
        print(entry.path)
    for task in wb.tasks.list().items:
        print(task.name)
```

## Classes and modules

Import the SDK's classes from the `wherobots` package, for example `from wherobots import WherobotsJob`. Each reference page shows its import.

| Name | Reference | Contents |
| - | - | - |
| `Wherobots` | [Wherobots client](https://docs.wherobots.com/reference/python-sdk/client.md) | The top-level client for files, tasks, and task runs. |
| `WherobotsJob` | [Job runs](https://docs.wherobots.com/reference/python-sdk/jobs.md) | Submit a job run, wait for it, read its logs, metrics, and cost, or cancel it. |
| `Files`, `FilesDrive`, `FilesAPI` | [Files](https://docs.wherobots.com/reference/python-sdk/files.md) | List, upload, download, rename, and delete files, and upload job scripts and dependencies. |
| `Tasks`, `TaskRuns` | [Tasks](https://docs.wherobots.com/reference/python-sdk/tasks.md) | List and run tasks, then follow each task run's state, logs, and cost. |
| `WherobotsConfig` | [Configuration](https://docs.wherobots.com/reference/python-sdk/config.md) | The API key, region, endpoint, and timeouts, read from arguments or environment variables. |
| `wherobots.models` | [Models](https://docs.wherobots.com/reference/python-sdk/models.md) | The dataclasses that SDK methods return, such as `RunView` and `TaskRun`. |
| `wherobots.enums` | [Enums](https://docs.wherobots.com/reference/python-sdk/enums.md) | Runtimes, regions, drives, and job run and task run statuses. |
| `wherobots.exceptions` | [Exceptions](https://docs.wherobots.com/reference/python-sdk/exceptions.md) | The SDK's exception classes, which all derive from `WherobotsJobError`. |

The SDK calls the endpoints described in the [Runs REST API](https://docs.wherobots.com/reference/runs.md) and the [API playground](https://docs.wherobots.com/api-playground/index.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.