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

# Tasks and task runs

> List and run tasks such as RasterFlow inference, then follow their runs, logs, and cost.

```python theme={"system"}
from wherobots import Tasks, TaskRuns
```

## TaskRuns

```python theme={"system"}
TaskRuns(client: BaseClient)
```

Runs of the organization's tasks.

Obtain it from `Wherobots.task_runs`; do not build it directly.

#### Parameters

**client** `BaseClient` *required*

The shared API connection.

### cancel()

```python theme={"system"}
cancel(task_run_id: str) -> None
```

Request that a run stop (`POST /task-runs/{id}/cancel`).

The run moves to `CANCELLING` and then `CANCELLED` once the stop is
confirmed.

#### Parameters

**task\_run\_id** `str` *required*

The run's id.

#### Raises

* `WherobotsAPIError`: On HTTP failures.

### cost()

```python theme={"system"}
cost(task_run_id: str) -> TaskRunCost
```

Fetch what a run cost (`GET /task-runs/{id}/cost`).

#### Parameters

**task\_run\_id** `str` *required*

The run's id.

#### Returns

**return** `TaskRunCost`

The run's cost; `is_settling` is `True` while it may still change.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures, or a cost the
  SDK cannot read (rather than reporting it as zero).

### get()

```python theme={"system"}
get(task_run_id: str) -> TaskRun
```

Fetch a run with its inputs and results (`GET /task-runs/{id}`).

#### Parameters

**task\_run\_id** `str` *required*

The run's id.

#### Returns

**return** `TaskRun`

The run.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures.

### list()

```python theme={"system"}
list(
    *,
    task_name: str | None = None,
    states: TaskRunState | str | Sequence[TaskRunState | str] | None = None,
    created_after: datetime | None = None,
    limit: int = 50,
    offset: int = 0,
) -> OffsetPage[TaskRunSummary]
```

List task runs, newest first (`GET /task-runs`).

#### Parameters

**task\_name** `str | None` (default: None)

Only runs of this task; a trailing `*` matches a prefix.

**states** `TaskRunState | str | Sequence[TaskRunState | str] | None` (default: None)

Only runs in this state, or in any of these states.

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

Only runs submitted after this instant; a naive
`datetime` is read as local time.

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

Page size, 1 to 100.

**offset** `int` (default: 0)

How many matching runs to skip.

#### Returns

**return** `OffsetPage[TaskRunSummary]`

One page of runs; `OffsetPage.next_offset` fetches the next.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures.

### logs()

```python theme={"system"}
logs(task_run_id: str, since: str | None = None) -> TaskRunLogs
```

Fetch a page of a run's logs (`GET /task-runs/{id}/logs`).

#### Parameters

**task\_run\_id** `str` *required*

The run's id.

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

The previous page's `next_since`; omit for the first page.

#### Returns

**return** `TaskRunLogs`

Log lines logged after `since`.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures.

## Tasks

```python theme={"system"}
Tasks(client: BaseClient, region: str | None = None)
```

The tasks the caller's organization can run.

Obtain it from `Wherobots.tasks`; do not build it directly.

#### Parameters

**client** `BaseClient` *required*

The shared API connection.

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

Region new runs use when `run` is given none; `None` lets the
API apply the organization's default region.

### get()

```python theme={"system"}
get(task_name: str) -> Task
```

Fetch a task with its input and output schemas (`GET /tasks/{name}`).

#### Parameters

**task\_name** `str` *required*

The task's name.

#### Returns

**return** `Task`

The task.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures.

### list()

```python theme={"system"}
list(
    *,
    regions: Region | str | Sequence[Region | str] | None = None,
    limit: int = 50,
    offset: int = 0,
) -> OffsetPage[TaskSummary]
```

List tasks, ordered by name (`GET /tasks`).

#### Parameters

**regions** `Region | str | Sequence[Region | str] | None` (default: None)

Only tasks that can run in this region, or in any of these regions.

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

Page size, 1 to 100.

**offset** `int` (default: 0)

How many matching tasks to skip.

#### Returns

**return** `OffsetPage[TaskSummary]`

One page of tasks; `OffsetPage.next_offset` fetches the next.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures.

### run()

```python theme={"system"}
run(
    task_name: str,
    inputs: Mapping[str, object] | None = None,
    *,
    region: Region | str | None = None,
    name: str | None = None,
) -> TaskRunSummary
```

Start a run of a task (`POST /tasks/{name}/runs`).

#### Parameters

**task\_name** `str` *required*

The task's name.

**inputs** `Mapping[str, object] | None` (default: None)

Inputs matching the task's `input_schema`.

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

Region to run in; defaults to the configured region, then to
the organization's default region.

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

A name for the run, shown as `TaskRun.name`.

#### Returns

**return** `TaskRunSummary`

The new run; poll `TaskRuns.get` with its `task_run_id`.

#### Raises

* `WherobotsAPIError`: On HTTP or JSON-parsing failures, including
  inputs the task's schema rejects.


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