Run a task

curl --request POST \
  --url https://api.cloud.wherobots.com/tasks/{taskName}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "region": "<string>",
  "inputs": {},
  "name": "<string>"
}
'

import requests

url = "https://api.cloud.wherobots.com/tasks/{taskName}/runs"

payload = {
    "region": "<string>",
    "inputs": {},
    "name": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({region: '<string>', inputs: {}, name: '<string>'})
};

fetch('https://api.cloud.wherobots.com/tasks/{taskName}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloud.wherobots.com/tasks/{taskName}/runs"

	payload := strings.NewReader("{\n  \"region\": \"<string>\",\n  \"inputs\": {},\n  \"name\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloud.wherobots.com/tasks/{taskName}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"region\": \"<string>\",\n  \"inputs\": {},\n  \"name\": \"<string>\"\n}")
  .asString();

{
  "taskRunId": "<string>",
  "taskName": "<string>",
  "state": "PENDING",
  "region": "<string>",
  "submittedAt": "2023-11-07T05:31:56Z",
  "taskId": "<string>",
  "taskTriggerId": "<string>",
  "type": "uniontask",
  "runSource": "manual",
  "batchTime": "2023-11-07T05:31:56Z",
  "rerunOfId": "<string>",
  "batchKind": "tick",
  "windowStart": "2023-11-07T05:31:56Z",
  "windowEnd": "2023-11-07T05:31:56Z",
  "noComputeReason": "cancelled",
  "failureClass": "QUOTA_REJECTED",
  "runAsId": "<string>",
  "requestedById": "<string>",
  "workload": {
    "type": "uniontask",
    "jobRunId": "<string>",
    "kubeAppId": "<string>",
    "unionExecutionId": "<string>"
  },
  "cancelRequestedAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "endedAt": "2023-11-07T05:31:56Z",
  "durationSeconds": 123
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

API playground

Run a task

Record a request to run a task, and answer with it PENDING.

region may be omitted for the organization’s default; whichever it was is stored on the run, since the default can change afterwards.

Platform scripts capture caller inputs plus publisher-fixed dependencies and Spark configs, then dispatch in the region as the caller, without a trigger or window. Scripts allow only args, runtime, version, timeoutSeconds and disk sizes; publisher settings cannot be overridden through this API. Union runs retain their existing launch-intent workload path. Direct execution does not require the task-scheduling feature flag.

Repeated POSTs create new runs. There is no HTTP creation idempotency or automatic stale-launch recovery for a crash after commit but before enqueue; cancel clears a stranded PENDING script run. Results remain null.

201: the run, PENDING. 400: the task runs nowhere, or not in this region, or the inputs do not satisfy its schema, or the organization is not set up to run in the region, or the region has no Temporal namespace configured; an error naming every problem. A submission whose inputs do not satisfy the schema is also kept in run history as REJECTED, with those problems and its inputs (bounded and sanitized, as stored_inputs describes); nothing is launched or billed. 404: no task of this name the caller’s organization may see — the same answer a read gives, so asking to run reveals no more than reading. 503: the run was recorded but its launch could not be dispatched; the run is marked FAILED and the request may be retried. For platform scripts, a retry creates a new run; the failed run remains in history as a PLATFORM failure.

POST

tasks

{taskName}

runs

Run a task

curl --request POST \
  --url https://api.cloud.wherobots.com/tasks/{taskName}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "region": "<string>",
  "inputs": {},
  "name": "<string>"
}
'

import requests

url = "https://api.cloud.wherobots.com/tasks/{taskName}/runs"

payload = {
    "region": "<string>",
    "inputs": {},
    "name": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({region: '<string>', inputs: {}, name: '<string>'})
};

fetch('https://api.cloud.wherobots.com/tasks/{taskName}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloud.wherobots.com/tasks/{taskName}/runs"

	payload := strings.NewReader("{\n  \"region\": \"<string>\",\n  \"inputs\": {},\n  \"name\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloud.wherobots.com/tasks/{taskName}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"region\": \"<string>\",\n  \"inputs\": {},\n  \"name\": \"<string>\"\n}")
  .asString();

{
  "taskRunId": "<string>",
  "taskName": "<string>",
  "state": "PENDING",
  "region": "<string>",
  "submittedAt": "2023-11-07T05:31:56Z",
  "taskId": "<string>",
  "taskTriggerId": "<string>",
  "type": "uniontask",
  "runSource": "manual",
  "batchTime": "2023-11-07T05:31:56Z",
  "rerunOfId": "<string>",
  "batchKind": "tick",
  "windowStart": "2023-11-07T05:31:56Z",
  "windowEnd": "2023-11-07T05:31:56Z",
  "noComputeReason": "cancelled",
  "failureClass": "QUOTA_REJECTED",
  "runAsId": "<string>",
  "requestedById": "<string>",
  "workload": {
    "type": "uniontask",
    "jobRunId": "<string>",
    "kubeAppId": "<string>",
    "unionExecutionId": "<string>"
  },
  "cancelRequestedAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "endedAt": "2023-11-07T05:31:56Z",
  "durationSeconds": 123
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

{
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "<string>",
      "details": "<string>",
      "path": "<string>",
      "suggestion": "Contact us at support@wherobots.com to get help with resolving your error.",
      "documentation_url": "<string>",
      "field": "<string>"
    }
  ],
  "requestId": "<string>"
}

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_uri": "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": "SUBMITTED", "region": "aws-us-west-2", "submittedAt": "2026-06-04T18:00:00Z" }

taskRunId

string

required

taskName

string

required

Current mutable Task display metadata, not historical identity.

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

taskId

string | null

taskTriggerId

string | null

type

enum<string> | null

Concrete task polymorphic identities.

Available options:

uniontask,

scripttask

runSource

enum<string>

default:manual

Origin of a run, independent of its backend.

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 nominal schedule time, gap for a journal boundary such as 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

Journal outcomes that deliberately launch no workload.

Available options:

cancelled,

overlap,

epoch_gap,

inputs_rejected

failureClass

enum<string> | null

Terminal dispatch and execution failure categories.

Available options:

QUOTA_REJECTED,

CONFIG_REJECTED,

USER_CODE,

PLATFORM,

TIMEOUT

runAsId

string | null

requestedById

string | null

workload

TaskRunWorkload · object | null

Recorded execution identity; absent before launch, never inferred from Task Run ID.

Show child attributes

cancelRequestedAt

string<date-time> | null

startedAt

string<date-time> | null

endedAt

string<date-time> | null

durationSeconds

integer | null

How long the backend executed the run, from its start to its end (or to now, while running). 0 if it never started there. 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.