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

# Job runs (WherobotsJob)

> Submit a Python script or JAR as a job run, then wait for it, read its logs, or cancel it.

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

## WherobotsJob

```python theme={"system"}
WherobotsJob(
    script: str,
    name: str,
    runtime: str | Runtime | None = None,
    region: str | Region | None = None,
    api_key: str | None = None,
    version: str | None = None,
    timeout_seconds: int = 3600,
    args: list[str] | None = None,
    spark_configs: dict[str, str] | None = None,
    dependencies: list[dict[str, Any]] | None = None,
    spark_driver_disk_gb: int | None = None,
    spark_executor_disk_gb: int | None = None,
    s3_bucket: str | None = None,
    s3_prefix: str | None = None,
    jar_main_class: str | None = None,
    auto_upload: bool = True,
    base_url: str | None = None,
    request_timeout_seconds: int | None = None,
    config: WherobotsConfig | None = None,
    client_chain: str | None = None,
)
```

Wherobots Job Run Manager.

Manages the lifecycle of Wherobots job runs including submission,
monitoring, log streaming, and cancellation.

Use `from_run_id` to attach to an existing run for read-only
log/metrics access without binding a script.

Initialize a Wherobots Job.

#### Parameters

**script** `str` *required*

Path to Python script (.py) or JAR file (.jar).
Can be local path or S3 URI (s3://bucket/key)

**name** `str` *required*

Job name (8-255 chars, alphanumeric, \_, -, .)

**runtime** `str | Runtime | None` (default: None)

The compute runtime to use. Accepts a `Runtime` enum
value or a raw string; strings are passed to the API as-is.
Override the default runtime set for your organization — only
set this if you need a specific runtime instead of the one your
administrator has configured. When omitted, your organization's
default runtime is used.

**region** `str | Region | None` (default: None)

The compute region to run in. Accepts a `Region` enum
value or a raw string (e.g. a BYOC region such as
`byoc-acme-us-east-1`); strings are passed to the API as-is.
Override the default region set for your organization — only set
this if you intend to use a specific region instead of the one
your administrator has configured. When omitted, your
organization's default region is used.

**api\_key** `str | None` (default: None)

Wherobots API key (or set WHEROBOTS\_API\_KEY env var)

**version** `str | None` (default: None)

Wherobots version ("latest" or "preview")

**timeout\_seconds** `int` (default: 3600)

Job timeout in seconds (default: 3600)

**args** `list[str] | None` (default: None)

Optional list of arguments to pass to script

**spark\_configs** `dict[str, str] | None` (default: None)

Optional Spark configuration dict

**dependencies** `list[dict[str, Any]] | None` (default: None)

Optional list of PyPI or file dependencies

**spark\_driver\_disk\_gb** `int | None` (default: None)

Optional driver disk size

**spark\_executor\_disk\_gb** `int | None` (default: None)

Optional executor disk size

**s3\_bucket** `str | None` (default: None)

Deprecated. Ignored; presigned uploads are used
instead. Will be removed in a future release.

**s3\_prefix** `str | None` (default: None)

Deprecated. Ignored; presigned uploads are used
instead. Will be removed in a future release.

**jar\_main\_class** `str | None` (default: None)

Main class for JAR files (required for JARs)

**auto\_upload** `bool` (default: True)

Automatically upload local scripts via presigned
URL (default: True)

**base\_url** `str | None` (default: None)

Override the API base URL

**request\_timeout\_seconds** `int | None` (default: None)

HTTP request timeout in seconds

**config** `WherobotsConfig | None` (default: None)

Optional WherobotsConfig to override defaults

**client\_chain** `str | None` (default: None)

Upstream `X-Wherobots-Client` chain for tools
that embed this SDK. The SDK appends its own hop to the
right of it so the originating client stays leftmost.
Advisory only — it never affects authentication.

#### Raises

* `WherobotsValidationError`: If script is None/empty, disk sizes
  are negative, or jar\_main\_class is missing for JARs.

### add\_file\_dependency()

```python theme={"system"}
WherobotsJob.add_file_dependency(file_path: str) -> dict[str, Any]
```

Create a file dependency entry.

Accepts either an `s3://` URI (used as-is) or a local file
path. Local paths are marked for **lazy upload** at
`submit()` time — auto-upload always targets managed storage.

Need to upload to a Storage Integration (or a custom subdir)?
Use `wherobots.FilesAPI` directly to upload, then pass
the resulting `s3://` URI here. Keeps this method focused
on dependency declaration; `FilesAPI` owns "where files
go."

#### Parameters

**file\_path** `str` *required*

`s3://...` URI **or** local filesystem path
ending in `.jar`, `.whl`, `.zip`, or `.json`.

#### Returns

**return** `dict[str, Any]`

Dependency dictionary. May carry an internal
`_pendingUpload` sentinel when a local path is given;
it is stripped during request building.

#### Raises

* `WherobotsValidationError`: If the extension is not one of
  `.jar` / `.whl` / `.zip` / `.json`.

### add\_pypi\_dependency()

```python theme={"system"}
WherobotsJob.add_pypi_dependency(
    library_name: str,
    library_version: str,
) -> dict[str, str]
```

Create a PyPI dependency object.

#### Parameters

**library\_name** `str` *required*

PyPI package name

**library\_version** `str` *required*

Package version

#### Returns

**return** `dict[str, str]`

Dependency dictionary

### cancel()

```python theme={"system"}
cancel() -> bool
```

Cancel the job run.

#### Returns

**return** `bool`

True if cancellation request was successful

### close()

```python theme={"system"}
close() -> None
```

Close the underlying API session.

Should be called when the job manager is no longer needed,
or use as a context manager instead.

### from\_run\_id()

```python theme={"system"}
WherobotsJob.from_run_id(
    run_id: str,
    *,
    api_key: str | None = None,
    config: WherobotsConfig | None = None,
    base_url: str | None = None,
    region: str | None = None,
    request_timeout_seconds: int | None = None,
    client_chain: str | None = None,
) -> WherobotsJob
```

Attach to an existing run for read-only log/metric access.

Unlike the regular constructor this does not require a script
or name — only a `run_id`. The returned instance is read-only:
`submit` will raise. All other read methods (`get_logs`,
`iter_logs`, `poll_for_logs`, `get_metrics`,
`get_cpu_utilization`, `get_mem_utilization`, `get_status`,
`cancel`, `wait_for_completion`) work normally.

#### Parameters

**run\_id** `str` *required*

Run identifier from a prior submission, the CLI, or
the Wherobots UI.

**api\_key** `str | None` (default: None)

Wherobots API key (or set `WHEROBOTS_API_KEY`).

**config** `WherobotsConfig | None` (default: None)

Pre-built `WherobotsConfig` to use instead of the
environment.

**base\_url** `str | None` (default: None)

Override the API base URL.

**region** `str | None` (default: None)

AWS region override.

**request\_timeout\_seconds** `int | None` (default: None)

HTTP request timeout in seconds.

**client\_chain** `str | None` (default: None)

Upstream `X-Wherobots-Client` chain for tools
that embed this SDK. The SDK appends its own hop to the
right of it so the originating client stays leftmost.

#### Returns

**return** `WherobotsJob`

A `WherobotsJob` bound to *run\_id* with descriptive
fields (name, runtime, status, ...) hydrated from the API.

#### Raises

* `WherobotsValidationError`: If *run\_id* is empty.
* `WherobotsAPIError`: If the initial refresh fails.

### get\_consumed\_spatial\_units()

```python theme={"system"}
get_consumed_spatial_units() -> float | None
```

Get the spatial units (SUs) consumed by the run.

#### Returns

**return** `float | None`

SUs consumed (e.g. `11.27`), or `None` if not reported.

### get\_cost()

```python theme={"system"}
get_cost() -> float | None
```

Get the run's total cost in USD.

#### Returns

**return** `float | None`

Cost in USD (e.g. `16.90`), or `None` if the server did
not surface a cost for this run (typical for runs that are
still running or have not yet been billed).

### get\_cpu\_utilization()

```python theme={"system"}
get_cpu_utilization() -> UtilizationStats
```

Get aggregated CPU utilization for the run.

#### Returns

**return** `UtilizationStats`

`UtilizationStats` with `latest`/`max`/`avg`/`series`.
All fields are `None`/empty when the CPU metric is absent
from the server response.

### get\_logs()

```python theme={"system"}
get_logs(cursor: int | str = 0, size: int = 100) -> LogsResponse
```

Get job logs.

#### Parameters

**cursor** `int | str` (default: 0)

Position to start reading logs. Accepts integer byte
offsets (legacy) or string cursors returned in
`LogsResponse.next_page`. Defaults to `0`.

**size** `int` (default: 100)

Maximum number of log entries to retrieve (default: 100)

#### Returns

**return** `LogsResponse`

LogsResponse with items and pagination info

### get\_mem\_utilization()

```python theme={"system"}
get_mem_utilization() -> UtilizationStats
```

Get aggregated memory utilization for the run.

#### Returns

**return** `UtilizationStats`

`UtilizationStats` with `latest`/`max`/`avg`/`series`.
All fields are `None`/empty when the memory metric is
absent from the server response.

### get\_metrics()

```python theme={"system"}
get_metrics() -> RunMetricsResponse
```

Get job metrics for the run.

#### Returns

**return** `RunMetricsResponse`

RunMetricsResponse with series and instant metrics

### get\_status()

```python theme={"system"}
get_status() -> RunView
```

Get current job status and details.

#### Returns

**return** `RunView`

RunView with full job details

### iter\_logs()

```python theme={"system"}
iter_logs(
    cursor: int | str = 0,
    size: int = 100,
    max_pages: int = 10000,
) -> Iterator[dict[str, Any]]
```

Iterate over log entries until pagination ends.

#### Parameters

**cursor** `int | str` (default: 0)

Initial pagination cursor.

**size** `int` (default: 100)

Page size passed to `get_logs`.

**max\_pages** `int` (default: 10000)

Hard ceiling on pages fetched, to guard against a
buggy server that always returns a distinct
`next_page` cursor. Defaults to `10_000`.

#### Raises

* `WherobotsJobError`: If the page ceiling is hit.

### list\_runs()

```python theme={"system"}
WherobotsJob.list_runs(
    api_key: str | None = None,
    region: str | None = None,
    name_pattern: str | None = None,
    created_after: str | None = None,
    status: list[str | JobStatus] | None = None,
    cursor: str | None = None,
    size: int = 50,
    base_url: str | None = None,
    request_timeout_seconds: int | None = None,
    config: WherobotsConfig | None = None,
) -> RunListPage
```

List job runs in the organization.

#### Parameters

**api\_key** `str | None` (default: None)

Wherobots API key (or use WHEROBOTS\_API\_KEY env var)

**region** `str | None` (default: None)

Filter by region

**name\_pattern** `str | None` (default: None)

Filter by name pattern (supports \* wildcard)

**created\_after** `str | None` (default: None)

Filter runs created after this ISO timestamp

**status** `list[str | JobStatus] | None` (default: None)

Filter by status (list of statuses)

**cursor** `str | None` (default: None)

Pagination cursor

**size** `int` (default: 50)

Number of results per page (default: 50, max: 100)

**base\_url** `str | None` (default: None)

Override API base URL

**request\_timeout\_seconds** `int | None` (default: None)

HTTP request timeout in seconds

**config** `WherobotsConfig | None` (default: None)

Optional WherobotsConfig to override defaults

#### Returns

**return** `RunListPage`

RunListPage with items, total, and pagination cursor

### poll\_for\_logs()

```python theme={"system"}
poll_for_logs(
    follow: bool = True,
    interval: float = 2.0,
    log_handler: Callable[[dict[str, Any]], None] | None = None,
    max_errors: int = 10,
    _deadline: float | None = None,
) -> None
```

Poll and print job logs.

#### Parameters

**follow** `bool` (default: True)

If True, continue polling until job completes.

**interval** `float` (default: 2.0)

Polling interval in seconds (default: 2.0).

**log\_handler** `Callable[[dict[str, Any]], None] | None` (default: None)

Optional handler for each log item dict.

**max\_errors** `int` (default: 10)

Max consecutive transient errors before giving up
(default: 10). Non-transient errors (4xx except 429)
are raised immediately.

**\_deadline** `float | None` (default: None)

Internal. Monotonic clock deadline for timeout
enforcement.  Callers should use
`wait_for_completion(max_wait_seconds=...)` instead.

#### Raises

* `WherobotsJobError`: If the job has not been submitted.
* `WherobotsTimeoutError`: If *\_deadline* is set and exceeded.
* `WherobotsAPIError`: On non-transient HTTP errors.

### refresh()

```python theme={"system"}
refresh() -> RunView
```

Re-fetch the run from the API and update local fields.

Updates `status`, `name`, `runtime`, `region`, and
`version` in place. Works in both attached and submitted modes.

#### Returns

**return** `RunView`

The freshly fetched `RunView`.

#### Raises

* `WherobotsJobError`: If `run_id` is not set.

### submit()

```python theme={"system"}
submit() -> str
```

Submit the job run.

#### Returns

**return** `str`

Run ID

### wait\_for\_completion()

```python theme={"system"}
wait_for_completion(
    poll_interval: float = 5.0,
    stream_logs: bool = True,
    log_interval: float = 2.0,
    max_wait_seconds: float | None = None,
) -> JobStatus | str
```

Wait for job to complete, optionally streaming logs.

#### Parameters

**poll\_interval** `float` (default: 5.0)

Status check interval in seconds (default: 5.0)

**stream\_logs** `bool` (default: True)

Stream logs while waiting (default: True)

**log\_interval** `float` (default: 2.0)

Log polling interval in seconds (default: 2.0)

**max\_wait\_seconds** `float | None` (default: None)

Maximum time to wait before raising
`WherobotsTimeoutError`.  `None` means wait
indefinitely (default: None).

#### Returns

**return** `JobStatus | str`

Final job status

#### Raises

* `WherobotsTimeoutError`: If max\_wait\_seconds is exceeded.


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