Run a task
Start a run of a task with the given inputs.
The run starts PENDING. Poll GET /task-runs/{taskRunId} for its state and results.
region defaults to the organization’s default region. Each request creates a new run.
- 400: the region is invalid, the task or your organization cannot run in it, or the
inputs do not match the task’s input schema. The region is checked first. An inputs
error lists every input problem, and the run is normally kept in run history as
REJECTED; nothing is launched or billed. - 403: you may not run tasks, or your organization may not use this region.
- 404: no task with this name is available to your organization.
- 503: the run may not have started. It usually reads
FAILED, but it can still start, so find it withGET /task-runsbefore running the task again. On your organization’s first run in a region, a 503 can instead mean the region could not be set up for it in time; then no run was created, and you can retry after theRetry-Afterdelay.
Authorizations
Path Parameters
Body
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"
}
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" }
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.

