> ## Documentation Index > Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://api.cloud.wherobots.com/openapi.json post /tasks/{taskName}/runs openapi: 3.1.0 info: title: Wherobots Cloud API description: |- Wherobots Cloud API OpenAPI specification. These are the API docs for the Wherobots API. You can use this to test out the API and see what it does. The underlying OPENAPI spec can be found at /openapi.json. This can be used to generate clients for the API. The Authorize button below will allow you to input an access token to authenticate to our API. Then all of the requests on the page should work. version: 0.0.1 servers: - url: https://api.cloud.wherobots.com description: Wherobots Cloud API security: [] paths: /tasks/{taskName}/runs: post: tags: - tasks summary: Run a task description: >- 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. operationId: createTaskRun parameters: - name: taskName in: path required: true schema: type: string minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9_\-\.]+$ description: The name of the task. title: Taskname description: The name of the task. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTaskRunPayload' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskRunSummary' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorBody' security: - bearerToken: [] - wherobotsApiKey: [] components: schemas: CreateTaskRunPayload: properties: region: anyOf: - type: string - type: 'null' title: Region inputs: additionalProperties: true type: object title: Inputs name: anyOf: - type: string maxLength: 255 - type: 'null' title: Name additionalProperties: false type: object title: CreateTaskRunPayload description: >- ``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" } TaskRunSummary: properties: taskRunId: type: string title: Taskrunid taskName: type: string title: Taskname description: Current mutable Task display metadata, not historical identity. taskId: anyOf: - type: string - type: 'null' title: Taskid taskTriggerId: anyOf: - type: string - type: 'null' title: Tasktriggerid type: anyOf: - $ref: '#/components/schemas/TaskKind' - type: 'null' runSource: $ref: '#/components/schemas/RunSource' default: manual batchTime: anyOf: - type: string format: date-time - type: 'null' title: Batchtime rerunOfId: anyOf: - type: string - type: 'null' title: Rerunofid description: >- The task run this one reran, when runSource is rerun. Null otherwise. batchKind: anyOf: - $ref: '#/components/schemas/BatchKind' - type: 'null' description: >- 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. windowStart: anyOf: - type: string format: date-time - type: 'null' title: Windowstart windowEnd: anyOf: - type: string format: date-time - type: 'null' title: Windowend noComputeReason: anyOf: - $ref: '#/components/schemas/NoComputeReason' - type: string - type: 'null' title: Nocomputereason failureClass: anyOf: - $ref: '#/components/schemas/FailureClass' - type: 'null' runAsId: anyOf: - type: string - type: 'null' title: Runasid requestedById: anyOf: - type: string - type: 'null' title: Requestedbyid workload: anyOf: - $ref: '#/components/schemas/TaskRunWorkload' - type: 'null' state: $ref: '#/components/schemas/TaskRunState' region: type: string title: Region submittedAt: type: string format: date-time title: Submittedat cancelRequestedAt: anyOf: - type: string format: date-time - type: 'null' title: Cancelrequestedat startedAt: anyOf: - type: string format: date-time - type: 'null' title: Startedat endedAt: anyOf: - type: string format: date-time - type: 'null' title: Endedat durationSeconds: anyOf: - type: integer - type: 'null' title: Durationseconds description: >- 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. type: object required: - taskRunId - taskName - state - region - submittedAt title: TaskRunSummary description: |- e.g. { "taskRunId": "npqy9q19q4wlm3", "taskName": "predict_mosaic_geometries_recipe", "state": "SUBMITTED", "region": "aws-us-west-2", "submittedAt": "2026-06-04T18:00:00Z" } ErrorBody: properties: errors: items: $ref: '#/components/schemas/ErrorInfo' type: array title: Errors description: A list of errors that occurred requestId: type: string title: Requestid description: A unique identifier for the request that caused the error type: object required: - errors - requestId title: ErrorBody TaskKind: type: string enum: - uniontask - scripttask title: TaskKind description: Concrete task polymorphic identities. RunSource: type: string enum: - manual - schedule - rerun title: RunSource description: Origin of a run, independent of its backend. BatchKind: type: string enum: - tick - gap title: BatchKind description: 'Meaning of a run''s batch timestamp: nominal tick or journal boundary.' NoComputeReason: type: string enum: - cancelled - overlap - epoch_gap - inputs_rejected title: NoComputeReason description: Journal outcomes that deliberately launch no workload. FailureClass: type: string enum: - QUOTA_REJECTED - CONFIG_REJECTED - USER_CODE - PLATFORM - TIMEOUT title: FailureClass description: Terminal dispatch and execution failure categories. TaskRunWorkload: properties: type: $ref: '#/components/schemas/TaskKind' jobRunId: anyOf: - type: string - type: 'null' title: Jobrunid kubeAppId: anyOf: - type: string - type: 'null' title: Kubeappid unionExecutionId: anyOf: - type: string - type: 'null' title: Unionexecutionid type: object required: - type title: TaskRunWorkload description: >- Recorded execution identity; absent before launch, never inferred from Task Run ID. TaskRunState: type: string enum: - PENDING - SUBMITTED - RUNNING - SUCCEEDED - FAILED - TIMED_OUT - CANCELLING - CANCELLED - UNKNOWN - SKIPPED - MISSED - REJECTED title: TaskRunState ErrorInfo: properties: code: $ref: '#/components/schemas/ErrorClass' description: The error code message: type: string title: Message description: A human-readable message describing the error details: type: string title: Details description: Details about the error path: type: string title: Path description: The path to the field that caused the error suggestion: type: string title: Suggestion description: Suggested action to resolve the error default: >- Contact us at support@wherobots.com to get help with resolving your error. documentation_url: anyOf: - type: string - type: 'null' title: Documentation Url description: URL to related documentation field: anyOf: - type: string - type: 'null' title: Field description: The field that caused the error if applicable type: object required: - code - message - details - path title: ErrorInfo ErrorClass: type: string enum: - BAD_REQUEST_ERROR - CONFLICT_ERROR - INVALID_INPUT_ERROR - INTERNAL_SERVER_ERROR - UNAUTHORIZED_ERROR - INSUFFICIENT_PERMISSIONS_ERROR - THIRD_PARTY_PERMISSIONS_ERROR - NOT_FOUND_ERROR - INSUFFICIENT_QUOTA_ERROR - REQUEST_ENTITY_TOO_LARGE - FOREIGN_CATALOG_CONNECTION_FAILED - RATE_LIMIT_ERROR - RESOURCE_BUSY - TIMEOUT_ERROR - ACCOUNT_NOT_PROVISIONED - BAD_GATEWAY_ERROR - GATEWAY_TIMEOUT_ERROR - NOT_IMPLEMENTED_ERROR - GONE_ERROR title: ErrorClass securitySchemes: bearerToken: type: http scheme: bearer wherobotsApiKey: type: apiKey description: A Wherobots-generated API key in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.