Skip to main content

TaskRuns

Runs of the organization’s tasks. Obtain it from Wherobots.task_runs; do not build it directly.

Parameters

BaseClient
required
The shared API connection.

cancel()

Request that a run stop (POST /task-runs/{id}/cancel). The run moves to CANCELLING and then CANCELLED once the stop is confirmed.

Parameters

str
required
The run’s id.

Raises

  • WherobotsAPIError: On HTTP failures.

cost()

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

Parameters

str
required
The run’s id.

Returns

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()

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

Parameters

str
required
The run’s id.

Returns

TaskRun
The run.

Raises

  • WherobotsAPIError: On HTTP or JSON-parsing failures.

list()

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

Parameters

str | None
default:"None"
Only runs of this task; a trailing * matches a prefix.
TaskRunState | str | Sequence[TaskRunState | str] | None
default:"None"
Only runs in this state, or in any of these states.
datetime | None
default:"None"
Only runs submitted after this instant; a naive datetime is read as local time.
int
default:"50"
Page size, 1 to 100.
int
default:"0"
How many matching runs to skip.

Returns

OffsetPage[TaskRunSummary]
One page of runs; OffsetPage.next_offset fetches the next.

Raises

  • WherobotsAPIError: On HTTP or JSON-parsing failures.

logs()

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

Parameters

str
required
The run’s id.
str | None
default:"None"
The previous page’s next_since; omit for the first page.

Returns

TaskRunLogs
Log lines logged after since.

Raises

  • WherobotsAPIError: On HTTP or JSON-parsing failures.

wait_for_completion()

Poll a run until it finishes and return it. Works for any task. Polls start poll_interval apart and back off to 30 seconds apart (or poll_interval, if longer); state changes are logged at INFO. Neither a timeout nor an interrupt cancels the run: it keeps going on the server, and calling this again resumes the wait. Use cancel to stop it. UNKNOWN is not treated as finished until the run has reported it for 10 minutes in a row, because the server also uses it while a run starts. A state this SDK predates is never treated as finished; the wait logs a warning once and keeps polling, so set max_wait_seconds to bound it. When a run succeeds with its results briefly unavailable, it is fetched up to three more times, within max_wait_seconds, before it is returned without them. Script tasks never return results and are not refetched. A status check that fails with a rate limit (429), a server error (5xx) or a connection error is logged at WARNING and skipped, and the wait carries on; only a check that succeeds can end it. Five such failures in a row raise the last one. Other errors, such as a 404 or a response the SDK can’t decode, raise at once.

Parameters

str
required
The run’s id.
float
default:"5.0"
Seconds before the first re-check, greater than zero.
float | None
default:"None"
Stop waiting after this many seconds; None waits as long as the run takes. The last check can return just after the deadline; if it finds the run finished, the run is returned rather than a timeout, so a finished result is never thrown away.
bool
default:"True"
Raise if the run ends in any state but SUCCEEDED; False returns the run instead.

Returns

TaskRun
The finished run.

Raises

  • WherobotsAPIError: On HTTP or JSON-parsing failures.
  • WherobotsTaskRunError: The run did not succeed and raise_on_failure is set. .run holds the finished run.
  • WherobotsTaskRunTimeoutError: max_wait_seconds passed. The run keeps going; .run holds it as last fetched. A WherobotsTimeoutError.
  • WherobotsValidationError: poll_interval is not greater than zero.

Tasks

The tasks the caller’s organization can run. Obtain it from Wherobots.tasks; do not build it directly.

Parameters

BaseClient
required
The shared API connection.
str | None
default:"None"
Region new runs use when run is given none; None lets the API apply the organization’s default region.

get()

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

Parameters

str
required
The task’s name.

Returns

Task
The task.

Raises

  • WherobotsAPIError: On HTTP or JSON-parsing failures.

list()

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

Parameters

Region | str | Sequence[Region | str] | None
default:"None"
Only tasks that can run in this region, or in any of these regions.
int
default:"50"
Page size, 1 to 100.
int
default:"0"
How many matching tasks to skip.

Returns

OffsetPage[TaskSummary]
One page of tasks; OffsetPage.next_offset fetches the next.

Raises

  • WherobotsAPIError: On HTTP or JSON-parsing failures.

run()

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

Parameters

str
required
The task’s name.
Mapping[str, object] | None
default:"None"
Inputs matching the task’s input_schema.
Region | str | None
default:"None"
Region to run in; defaults to the configured region, then to the organization’s default region.
str | None
default:"None"
A name for the run, shown as TaskRun.name.

Returns

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.

run_and_wait()

Start a run of a task and wait for it to finish. run followed by TaskRuns.wait_for_completion; see those for the arguments. Read a single-output task’s result with TaskRun.output. For other wait options, call the two separately.

Parameters

str
required
Mapping[str, object] | None
default:"None"
Region | str | None
default:"None"
str | None
default:"None"
float | None
default:"None"

Returns

TaskRun
The finished run.

Raises

  • WherobotsAPIError: On HTTP or JSON-parsing failures.
  • WherobotsTaskRunError: The run did not succeed. .run holds the finished run.
  • WherobotsTaskRunTimeoutError: max_wait_seconds passed. The run keeps going; .run holds it as last fetched.