Skip to main content
POST
Run a task

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

taskName
string
required

The name of the task.

Required string length: 1 - 255
Pattern: ^[a-zA-Z0-9_\-\.]+$

Body

application/json

inputs must match the task's inputSchema from GET /tasks/{taskName}. The task's examples show sample inputs to start from.

e.g., for POST /tasks/predict_mosaic_geometries_recipe/runs: { "region": "aws-us-west-2", "inputs": { "aoi": "s3://wherobots-examples/rasterflow/aois/collegepark.parquet", "start": "2023-01-01T00:00:00Z", "end": "2024-01-01T00:00:00Z", "model_recipe": "sam3-text-geometry", "text_prompt": ["roofs"], "confidence_threshold": 0.3, "target_crs": "EPSG:3857" }, "name": "College Park roofs, 2023" }

region
string | null
inputs
Inputs · object
name
string | null
Maximum string length: 255

Response

Successful Response

e.g. { "taskRunId": "npqy9q19q4wlm3", "taskName": "predict_mosaic_geometries_recipe", "state": "PENDING", "region": "aws-us-west-2", "submittedAt": "2026-06-04T18:00:00Z" }

taskRunId
string
required
taskName
string
required

The task's current name, which may have changed since the run started.

state
enum<string>
required
Available options:
PENDING,
SUBMITTED,
RUNNING,
SUCCEEDED,
FAILED,
TIMED_OUT,
CANCELLING,
CANCELLED,
UNKNOWN,
SKIPPED,
MISSED,
REJECTED
region
string
required
submittedAt
string<date-time>
required

Submission time, before queueing and infrastructure startup.

taskId
string | null
taskTriggerId
string | null
type
enum<string> | null

How a task runs: as a Union workflow or as a script.

Available options:
uniontask,
scripttask
runSource
enum<string>
default:manual

What started a run: a person, a schedule, or a rerun.

Available options:
manual,
schedule,
rerun
batchTime
string<date-time> | null
rerunOfId
string | null

The task run this one reran, when runSource is rerun. Null otherwise.

batchKind
enum<string> | null

What batchTime means: tick for a scheduled time, gap for a pause or schedule edit. Null when batchTime is null.

Available options:
tick,
gap
windowStart
string<date-time> | null
windowEnd
string<date-time> | null
noComputeReason

Why a run finished without running.

Available options:
cancelled,
overlap,
epoch_gap,
inputs_rejected,
missed
failureClass
enum<string> | null

Why a run did not succeed.

Available options:
QUOTA_REJECTED,
CONFIG_REJECTED,
USER_CODE,
PLATFORM,
TIMEOUT
runAsId
string | null
requestedById
string | null
canCancel
boolean
default:false

Whether this caller may cancel the run, independent of run state.

workload
TaskRunWorkload · object | null

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

cancelRequestedAt
string<date-time> | null
startedAt
string<date-time> | null

Workload execution start time, after queueing and infrastructure startup.

endedAt
string<date-time> | null
durationSeconds
integer | null

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.

errorMessage
string | null

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.