> ## 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. # List task runs > List task runs for the current organization, most recent first. Each run's state is derived from its backend execution, and the state filter matches that derived state. ## OpenAPI ````yaml https://api.cloud.wherobots.com/openapi.json get /task-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: /task-runs: get: tags: - task-runs summary: List task runs description: >- List task runs for the current organization, most recent first. Each run's state is derived from its backend execution, and the state filter matches that derived state. operationId: listTaskRuns parameters: - name: taskName in: query required: false schema: anyOf: - type: string maxLength: 255 pattern: ^[a-zA-Z0-9_\-\.]+\*?$ - type: 'null' description: >- Only return runs of this task. Exact name, or a prefix followed by '*'. title: Taskname description: >- Only return runs of this task. Exact name, or a prefix followed by '*'. - name: type in: query required: false schema: anyOf: - $ref: '#/components/schemas/TaskKind' - type: 'null' description: Only return runs of this type. title: Type description: Only return runs of this type. - name: state in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/TaskRunState' - type: 'null' description: >- Only return runs in these states. Repeat the parameter to pass several; a run matches if it is in any of them. title: State description: >- Only return runs in these states. Repeat the parameter to pass several; a run matches if it is in any of them. - name: createdAfter in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Only return runs submitted after this instant. title: Createdafter description: Only return runs submitted after this instant. - name: taskId in: query required: false schema: anyOf: - type: string - type: 'null' title: Taskid - name: taskTriggerId in: query required: false schema: anyOf: - type: string - type: 'null' title: Tasktriggerid - name: runSource in: query required: false schema: anyOf: - $ref: '#/components/schemas/RunSource' - type: 'null' title: Runsource - name: batchTimeFrom in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Inclusive nominal tick lower bound; excludes manual runs. title: Batchtimefrom description: Inclusive nominal tick lower bound; excludes manual runs. - name: batchTimeTo in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: Exclusive nominal tick upper bound; excludes manual runs. title: Batchtimeto description: Exclusive nominal tick upper bound; excludes manual runs. - name: userId in: query required: false schema: anyOf: - type: string minLength: 1 maxLength: 200 - type: 'null' description: Only return runs this user submitted or that run as this user. title: Userid description: Only return runs this user submitted or that run as this user. - name: region in: query required: false schema: anyOf: - type: string - type: 'null' title: Region - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Page size limit default: 50 title: Limit description: Page size limit - name: offset in: query required: false schema: type: integer minimum: 0 description: Page offset default: 0 title: Offset description: Page offset responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LimitOffsetPage_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: TaskKind: type: string enum: - uniontask - scripttask title: TaskKind description: Concrete task polymorphic identities. TaskRunState: type: string enum: - PENDING - SUBMITTED - RUNNING - SUCCEEDED - FAILED - TIMED_OUT - CANCELLING - CANCELLED - UNKNOWN - SKIPPED - MISSED - REJECTED title: TaskRunState RunSource: type: string enum: - manual - schedule - rerun title: RunSource description: Origin of a run, independent of its backend. LimitOffsetPage_TaskRunSummary_: properties: items: items: $ref: '#/components/schemas/TaskRunSummary' type: array title: Items total: type: integer minimum: 0 title: Total limit: type: integer minimum: 1 title: Limit offset: type: integer minimum: 0 title: Offset type: object required: - items - total - limit - offset title: LimitOffsetPage[TaskRunSummary] 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 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" } 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 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. 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.