Skip to main content

CreateRunPayload

Body of POST /runs.

Parameters

RunEnvironment | None
default:"None"
str
required
RunJarPayload | None
default:"None"
RunPythonPayload | None
default:"None"
str | None
default:"None"
int
default:"3600"
Maximum execution time in seconds, measured from when the workload starts running. Time spent queued or starting infrastructure does not count.
str | None
default:"None"

CreateTaskRunPayload

Body of POST /tasks/{taskName}/runs. inputs must match the task’s input_schema.

Parameters

dict[str, object]
default:"dict()"
str | None
default:"None"
str | None
default:"None"

DataValue

One timestamped metric sample.

Parameters

int
required
float | None
required

DirectoryPage

Result of a directory listing operation.

Parameters

str | None
default:"None"
list[FileEntry]
required
bool
default:"False"
str
required
str | None
default:"None"
str
required
bool
default:"False"

DownloadUrlResponse

Short-lived storage location, to be fetched without platform credentials.

Parameters

str
required
datetime
required

ErrorBody

Body of an API error response.

Parameters

list[ErrorInfo]
required
A list of errors that occurred
str
required
A unique identifier for the request that caused the error

ErrorInfo

One error reported by the API.

Parameters

str
required
The error code
dict[str, str | int] | None
default:"None"
Machine-readable facts about the error a client can act on, when there are any
str
required
Details about the error
str | None
default:"None"
URL to related documentation
str | None
default:"None"
The field that caused the error if applicable
str
required
A human-readable message describing the error
str
required
The path to the field that caused the error
str
Suggested action to resolve the error

FileDependency

A file a run depends on, such as a JAR or wheel.

Parameters

str
required
DependencyType
default:"DependencyType.FILE"

FileEntry

One file or folder in a Files drive listing.

Parameters

str
required
FileEntryType
required
datetime | None
default:"None"
str
required
bool
default:"False"
int
default:"0"

is_dir

True for a folder.

FileUploadUrl

Presigned URL for uploading one file to a Files drive.

Parameters

str
required
str
required

InstantMetric

One metric value at a single point in time.

Parameters

DataValue
required
DataFormat
required

InstantMetricDetails

A display name and the instant values of one metric.

Parameters

str
required
InstantMetric
required

KubeAppCreationMeta

event_meta shape for EventCode.APP_START_CREATION.

Parameters

bool
default:"False"
str | None
default:"None"

KubeAppEvent

An event on a run’s Kubernetes application.

Parameters

str | None
default:"None"
datetime
required
RunEventMeta | KubeAppCreationMeta | NodeSchedulingMeta | None
default:"None"
str
required
str | None
default:"None"
datetime
required

LogItem

One log line from a run.

Parameters

str
required
str
required

LogsResponse

One page of GET /runs/{id}/logs.

Parameters

str
required
list[LogItem]
required
str | None
default:"None"
dict[str, object]
default:"dict()"
The response body as the server sent it.

NodeSchedulingMeta

Metadata captured at node-scheduling time.

Parameters

str
required
str
required
bool
required
str
required

OffsetPage

One page of a limit/offset listing.

Parameters

list[T]
required
int
required
int
required
int
required

next_offset

The offset of the next page, or None on the last page.

OrganizationCustomer

A user in an organization.

Parameters

datetime
required
str | None
default:"None"
str
required
str | None
default:"None"
list[object]
required
datetime
required

PyPiDependency

A PyPI package a run depends on.

Parameters

str
required
str | None
default:"None"
DependencyType
default:"DependencyType.PYPI"

ResolvedFileDependency

A file dependency as the API returns it.

Parameters

str
required
DependencyFileType
required
Get the type of the file
DependencyType
default:"DependencyType.FILE"

ResolvedRunEnvironment

The environment a run resolved to, as the API returns it.

Parameters

list[PyPiDependency | ResolvedFileDependency]
default:"list()"
dict[str, str]
default:"dict()"
int | None
default:"None"
int | None
default:"None"

RunAppMeta

Run-specific metadata fields

Parameters

str | None
default:"None"
str
default:"''"
str
default:"''"

RunEnvironment

Spark configuration, disk sizes and dependencies for a run.

Parameters

list[PyPiDependency | FileDependency]
default:"list()"
dict[str, str]
default:"dict()"
int | None
default:"None"
int | None
default:"None"

RunEventMeta

Execution timing and optional producer-attributed terminal failure cause.

Parameters

int | None
default:"None"
str | None
default:"None"
int | None
default:"None"

RunJarPayload

What a JAR run executes.

Parameters

list[str]
default:"list()"
str | None
default:"None"
str
required

RunKubeApp

Kubernetes application details for a run.

Parameters

dict[str, object] | None
default:"None"
RunAppMeta | None
default:"None"
AppType
required
int
required
datetime
required
str | None
required
list[KubeAppEvent]
default:"list()"
str
required
str
required
str | None
required
Return the latest trace info that is valuable for troubleshooting
str
required
AppStatus
required
datetime
required

RunListPage

One page of GET /runs.

Parameters

str | None
default:"None"
Cursor for the next page
str | None
default:"None"
Cursor to refetch the current page
str | None
default:"None"
Cursor to refetch the current page starting from the last item
list[RunView]
required
str | None
default:"None"
Cursor for the previous page
int
required
dict[str, object]
default:"dict()"
The response body as the server sent it.

cursor

Alias for next_page, kept for backward compatibility.

RunMetricsResponse

Response of GET /runs/{id}/metrics.

Parameters

dict[str, InstantMetricDetails]
required
dict[str, SeriesMetricDetails]
required
dict[str, object]
default:"dict()"
The response body as the server sent it.

instant_value()

Return one instant metric’s value.

Parameters

str
required
A WorkloadMetric name.

Returns

float | None
The value, or None when the server reported none.

RunPayload

The payload a run was created with, as the API returns it.

Parameters

ResolvedRunEnvironment | None
default:"None"
str
required
RunJarPayload | None
default:"None"
RunPythonPayload | None
default:"None"
str | None
default:"None"
int
default:"3600"
Maximum execution time in seconds, measured from when the workload starts running. Time spent queued or starting infrastructure does not count.
str | None
default:"None"

RunPythonPayload

What a Python run executes.

Parameters

list[str]
default:"list()"
str
required

RunView

A job run, as returned by GET /runs/{id}.

Parameters

datetime | None
default:"None"
datetime
required
RunKubeApp | None
default:"None"
RunPayload
required
dict[str, object]
default:"dict()"
The response body as the server sent it.
datetime | None
default:"None"
JobStatus
required
str
required
str
required
OrganizationCustomer
required
datetime
required

app_meta

Spark UI and resolved version details, once the workload exists.

completed_at

Alias for complete_time, kept for backward compatibility.

created_at

Alias for create_time, kept for backward compatibility.

environment

Spark configuration and dependencies.

is_terminal

True once the run has finished, by the server’s word when it gives one.

region

The region running the workload, once one is assigned.

run_jar

The JAR the run executes.

run_python

The Python script the run executes.

runtime

The compute runtime the run asked for.

started_at

Alias for start_time, kept for backward compatibility.

timeout_seconds

How long the run may execute.

version

The runtime version the run asked for.

SeriesMetric

One metric as samples over time.

Parameters

list[DataValue]
required
DataFormat
required

SeriesMetricDetails

A display name and the series of one metric.

Parameters

str
required
SeriesMetric
required

StorageCredentialsRequest

Request body for the unified storage credentials endpoint.

Parameters

str
default:"'read'"
Access mode for the credentials. ‘read’ returns read-only credentials; ‘read_write’ returns credentials that also allow writing.
int
default:"3600"
Requested credential lifetime in seconds.
str
required
S3 URI (e.g. s3://bucket/prefix) to obtain credentials for.
str
default:"'Minimal'"
Minimal preserves requested-path scoping. Default opts into credentials for a server-selected authorized scope, returned as matchedGrantTarget. Underlying IAM restrictions still apply within that scope.

StorageCredentialsResponse

Credentials with an optional server-selected target for client cache reuse.

Parameters

str
required
datetime
required
str | None
default:"None"
Returned for Default privilege when the scope has no competing credential sources. If absent, cache only for the exact request. A trailing slash denotes descendants only; otherwise match the exact path or slash-delimited descendants. Reuse requires the same access mode and unexpired credentials.
str
required
str
required
str
required

StorageIntegration

A storage source: managed storage or a customer S3 integration.

Parameters

StorageSourceType
required
object | None
default:"None"
datetime
required
str | None
default:"None"
str
required
str
required
str
required
bool
default:"False"
str
required
str | None
default:"None"
str | None
default:"None"
datetime
required
dict[str, object]
default:"dict()"
The response body as the server sent it.

is_managed

True if Wherobots manages this storage source.

Task

A task definition, as returned by GET /tasks/{taskName}.

Parameters

object | None
default:"None"
str | None
default:"None"
str
required
list[TaskExample]
default:"list()"
dict[str, object] | None
default:"None"
str
required
str | None
default:"None"
dict[str, object] | None
default:"None"
list[str]
default:"list()"
str | None
default:"None"

TaskExample

An example invocation of a task.

Parameters

dict[str, object]
default:"dict()"
str
required

TaskRun

A task run, as returned by GET /task-runs/{taskRunId}.

Parameters

TaskRunState
required
dict[str, object] | None
default:"None"
Named outputs of a succeeded platform task run. Null for script task runs (including all scheduled runs), runs that did not succeed, and when outputs are temporarily unavailable.
str
required
The task’s current name, which may have changed since the run started.
str
required
BatchKind | None
default:"None"
What batchTime means: tick for a scheduled time, gap for a pause or schedule edit. Null when batchTime is null.
datetime | None
default:"None"
bool
default:"False"
Whether the run returned a result stored by an earlier run of the same task with the same inputs, instead of executing. Only a run that succeeded stores its result; one that failed or was cancelled is never reused. False until the run has ended.
datetime | None
default:"None"
int | None
default:"None"
How long the run executed, from its start to its end (or to now, while running). 0 if it never started. A cached run executes nothing, so this is the moment it took to return the stored result, not how long the result took to produce.
datetime | None
default:"None"
str | None
default:"None"
Why a failed or timed-out run failed, when more is known than its failureClass: a short, user-safe reason the caller can act on (for example a configuration rejection such as an unavailable runtime), or, for a run that could not be started, a task run ID to quote to support. Null for cancelled runs and when nothing beyond failureClass is known. REJECTED runs explain their input problems on getTaskRun; their summaries in run lists and schedule history remain null.
dict[str, object] | None
default:"None"
The job run request the run launched, or the request it was about to launch if it never started. Files it references may have changed since.
FailureClass | None
default:"None"
dict[str, object]
default:"dict()"
str | None
default:"None"
NoComputeReason | str | None
default:"None"
str
required
str | None
default:"None"
str | None
default:"None"
The task run this one reran, when runSource is rerun. Null otherwise.
str | None
default:"None"
RunSource
default:"RunSource.MANUAL"
datetime | None
default:"None"
Workload execution start time, after queueing and infrastructure startup.
datetime
required
Submission time, before queueing and infrastructure startup.
str | None
default:"None"
str | None
default:"None"
TaskKind | None
default:"None"
datetime | None
default:"None"
datetime | None
default:"None"
TaskRunWorkload | None
default:"None"

is_active

Return True while the run may still change state.

output

The run’s one result, for tasks with a single output.

Returns

object
The value of the run’s only entry in results, whatever its type.

Raises

  • WherobotsTaskRunError: The run has not succeeded, has no results, or has several outputs (read results for those).

TaskRunCost

Cost of one task run.

Parameters

bool
required
str
required
Decimal
required
str
required
Decimal
required

TaskRunLogEntry

One log line from a task run.

Parameters

str
required
str
required
str
required
A UTC instant carried to the nanosecond, e.g. ‘2026-06-04T18:01:12.680610267Z’. A string, not a date-time: log timestamps are nanoseconds, and most date-time parsers round them off to microseconds. Emitted with as many fractional digits as the value needs, up to 9; 0 to 9 are accepted.

TaskRunLogs

One page of a task run’s logs.

Parameters

list[TaskRunLogEntry]
default:"list()"
str | None
default:"None"
str
required

TaskRunSummary

A task run as it appears in a listing.

Parameters

TaskRunState
required
BatchKind | None
default:"None"
What batchTime means: tick for a scheduled time, gap for a pause or schedule edit. Null when batchTime is null.
datetime | None
default:"None"
datetime | None
default:"None"
int | None
default:"None"
How long the run executed, from its start to its end (or to now, while running). 0 if it never started. A cached run executes nothing, so this is the moment it took to return the stored result, not how long the result took to produce.
datetime | None
default:"None"
str | None
default:"None"
Why a failed or timed-out run failed, when more is known than its failureClass: a short, user-safe reason the caller can act on (for example a configuration rejection such as an unavailable runtime), or, for a run that could not be started, a task run ID to quote to support. Null for cancelled runs and when nothing beyond failureClass is known. REJECTED runs explain their input problems on getTaskRun; their summaries in run lists and schedule history remain null.
FailureClass | None
default:"None"
NoComputeReason | str | None
default:"None"
str
required
str | None
default:"None"
str | None
default:"None"
The task run this one reran, when runSource is rerun. Null otherwise.
str | None
default:"None"
RunSource
default:"RunSource.MANUAL"
datetime | None
default:"None"
Workload execution start time, after queueing and infrastructure startup.
datetime
required
Submission time, before queueing and infrastructure startup.
str | None
default:"None"
str
required
The task’s current name, which may have changed since the run started.
str
required
str | None
default:"None"
TaskKind | None
default:"None"
datetime | None
default:"None"
datetime | None
default:"None"
TaskRunWorkload | None
default:"None"

is_active

Return True while the run may still change state.

TaskRunSummaryPage

One page of task runs.

Parameters

list[TaskRunSummary]
required
int
required
int
required
int
required

next_offset

The offset of the next page, or None on the last page.

TaskRunWorkload

The compute assigned to a run, once it has one. It can appear before the run starts.

Parameters

str | None
default:"None"
str | None
default:"None"
TaskKind
required
str | None
default:"None"

TaskSummary

A task as it appears in a listing. A null organization_id marks a platform task.

Parameters

str | None
default:"None"
str
required
str
required
str | None
default:"None"
list[str]
default:"list()"
str | None
default:"None"

TaskSummaryPage

One page of tasks.

Parameters

list[TaskSummary]
required
int
required
int
required
int
required

next_offset

The offset of the next page, or None on the last page.

TemporaryAwsCredentials

Short-lived AWS STS credentials vended by POST /storage/credentials. Scope is determined server-side from the requested S3 path: the server picks the right backing bucket (managed / releases / matching Storage Integration). Security posture:
  • Masked in repr/str. repr(creds) (and therefore str(creds) and any f-string interpolation) only show the last 4 characters of the access key ID. Secret + session token never appear.
  • Frozen. Attribute injection is rejected; wipe() is the only mutator (via object.__setattr__ internally).
  • No pickle / copy. __reduce__, __copy__, and __deepcopy__ raise TypeError so creds cannot be silently serialized to disk, queues, or another process.
  • Local eviction via wipe(). Zeros the secret fields and poisons expiration so any subsequent is_expired check returns True. Python strings are immutable so the original bytes may linger on the heap until garbage collection, but this drops our last live reference. AWS-side revocation is not possible via the SDK; rely on the short TTL (typically 1 h).

Parameters

str
required
str
required
str
required
datetime
required
str
required

from_response()

Wrap the getStorageCredentials response.

Parameters

StorageCredentialsResponse
required
The decoded API response.

Returns

TemporaryAwsCredentials
A new TemporaryAwsCredentials instance.

Raises

  • WherobotsAPIError: If a secret field is empty. The message names the field only, never a value.

is_expired()

True if these creds are within leeway_seconds of expiry.

Parameters

int
default:"60"

wipe()

Evict secret material from this object. Overwrites access_key_id / secret_access_key / session_token with empty strings and forces expiration into the past so any post-wipe reuse is detected by is_expired. Idempotent; safe to call multiple times.

UtilizationStats

Aggregated utilization for a single metric (e.g. CPU or memory). series holds the (timestamp, value) points the server reported. latest, max and avg are derived from it. All fields are None or empty when the metric was not present in the response.

Parameters

float | None
default:"None"
float | None
default:"None"
float | None
default:"None"
list[tuple[float, float]]
default:"list()"

from_metrics()

Summarize one metric, preferring its series over its instant value.

Parameters

RunMetricsResponse
required
The run’s metrics.
str
required
A WorkloadMetric name.

Returns

UtilizationStats
The stats, empty when the server reported neither.