> ## Documentation Index > Fetch the complete documentation index at: https://docs.deck.co/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a task run > Returns a single task run by ID, including its status, input, output, errors, and interaction state. ## OpenAPI ````yaml /api-reference/v2.json get /task-runs/{run_id} openapi: 3.1.1 info: title: Deck API version: 2.0.0 servers: - url: https://api.deck.co/v2 description: Production security: - BearerAuth: [] tags: - name: Agents - name: Components - name: Credentials - name: Event Destinations - name: Events - name: Sessions - name: Sources - name: Storage - name: Task Runs - name: Tasks - name: Test paths: /task-runs/{run_id}: get: tags: - Task Runs summary: Retrieve a task run description: >- Returns a single task run by ID, including its status, input, output, errors, and interaction state. operationId: getTaskRun parameters: - name: run_id in: path required: true schema: type: string description: Unique identifier for the task run (prefixed with `trun_`). - name: include in: query schema: type: string description: >- Comma-separated list of additional fields to include in the response. Supported values: `input`, `storage`, `artifacts`. Sections are omitted from the response (not returned as null) when their flag is not present. responses: '200': description: OK content: text/plain: schema: $ref: '#/components/schemas/GetTaskRunResponse' application/json: schema: $ref: '#/components/schemas/GetTaskRunResponse' text/json: schema: $ref: '#/components/schemas/GetTaskRunResponse' '400': description: Bad request — validation error or malformed input. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized. '403': description: Forbidden. '404': description: Not found — the requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Conflict — the request is valid but cannot be completed in the current state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Unprocessable content — the request body is understood but contains invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: GetTaskRunResponse: required: - id - object - status - result - task_id - credential_id - session_id - agent_id - source_id - runtime_ms - output - errors - interaction - created_at - updated_at - request_id type: object properties: id: type: string description: Unique identifier for the task run, prefixed with `trun_`. object: type: string description: Always `task_run`. status: type: string description: >- Run status: `queued`, `running`, `canceling`, `interaction_required`, `review_required`, `completed`, `canceled`, or `failed`. result: type: - 'null' - string description: >- Run result after completion: `success`, `failure`, or `unknown`. Null while running. task_id: type: string description: The task that was executed. Prefixed with `task_`. credential_id: type: - 'null' - string description: >- The credential used for authentication, if any. Prefixed with `cred_`. session_id: type: - 'null' - string description: The session this run executed within, if any. Prefixed with `sess_`. agent_id: type: string description: The agent that executed this run. Prefixed with `agt_`. source_id: type: - 'null' - string description: The source this run connected to, if any. Prefixed with `src_`. runtime_ms: pattern: ^-?(?:0|[1-9]\d*)$ type: - 'null' - integer - string format: int32 description: Execution time in milliseconds. input: oneOf: - type: 'null' - $ref: '#/components/schemas/JsonElement' description: Input data provided when the run was created. tokenized: type: - 'null' - array items: type: string description: >- Names of input fields whose values were tokenized when the run was created. The listed fields are removed from `input`. Returned alongside `input` (only when `include=input` is requested and one or more fields were vaulted); omitted otherwise. output: oneOf: - type: 'null' - $ref: '#/components/schemas/JsonElement' description: Output data produced by the task execution. storage: type: - 'null' - array items: $ref: '#/components/schemas/TaskRunStorageItem' description: >- Files captured during the run, each with inline extraction (if any). Returned only when `include=storage` is requested. artifacts: oneOf: - type: 'null' - $ref: '#/components/schemas/TaskRunArtifactData' description: >- Run-level visibility artifacts (screenshots). Returned only when `include=artifacts` is requested. errors: type: - 'null' - array items: $ref: '#/components/schemas/TaskRunError' description: Error details if the run failed. Same structure as API-level errors. interaction: oneOf: - type: 'null' - $ref: '#/components/schemas/JsonElement' description: >- Interaction details when the run is paused waiting for user input (e.g. MFA code, security question). created_at: type: string format: date-time description: ISO 8601 timestamp of when the resource was created. updated_at: type: string format: date-time description: ISO 8601 timestamp of when the resource was last updated. request_id: type: string description: >- Unique identifier for the API request. Include this when contacting support. description: A task run object representing a single execution of a task. ValidationErrorResponse: required: - errors type: object properties: type: type: - 'null' - string description: RFC 9110 problem type URI. title: type: - 'null' - string description: Short summary of the validation failure. status: type: - 'null' - integer description: HTTP status code. format: int32 errors: type: object additionalProperties: type: array items: type: string description: Validation errors grouped by field name. traceId: type: - 'null' - string description: Request trace identifier. description: Validation error returned for malformed requests (HTTP 400). ErrorResponse: required: - errors - request_id type: object properties: errors: type: array items: $ref: '#/components/schemas/TaskRunError' description: One or more errors that describe what went wrong. request_id: type: string description: Unique identifier for this request, useful for tracing. description: Standard error response. JsonElement: description: Arbitrary JSON value. TaskRunStorageItem: required: - id - object - file_name - file_type - file_size - purpose - created_at type: object properties: id: type: string description: Unique identifier for the storage item, prefixed with `stor_`. object: type: string description: Always `storage`. file_name: type: string description: Original file name. file_type: type: string description: MIME type of the file. file_size: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int64 description: Size of the file in bytes. url: type: - 'null' - string description: Signed URL to download the file. Time-limited. extraction: oneOf: - type: 'null' - $ref: '#/components/schemas/JsonElement' description: Extracted structured data from the file, if any. purpose: type: string enum: - attachment - extraction - output description: >- How the file relates to the run: `attachment` (a file you provided as task input for the agent to use), `extraction` (a file you provided as task input that Deck extracts data from directly, skipping the agent), or `output` (a file the agent captured during the run). created_at: type: string format: date-time description: When the storage item was created. description: >- A storage item embedded in the task run detail response when include=storage is requested. Includes the signed download URL and any inline extraction. TaskRunArtifactData: type: object properties: screenshots: type: array items: $ref: '#/components/schemas/TaskRunScreenshot' description: Screenshots captured during the run. description: >- Run-level visibility artifacts returned when include=artifacts is requested. TaskRunError: required: - type - code - message type: object properties: type: type: string description: >- Error category (e.g. `source`, `auth`, `task`, `rate_limit`). Determines the class of failure. code: type: string description: Machine-readable error code. Use this for programmatic handling. message: type: string description: >- Human-readable explanation. Do not rely on this for logic — it may change. field: type: - 'null' - string description: The input field that caused the error, when applicable. description: Error details for a failed task run. Same structure as API-level errors. TaskRunScreenshot: required: - file_name - file_type - file_size - created_at type: object properties: file_name: type: string description: Original file name. file_type: type: string description: MIME type of the screenshot. file_size: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int64 description: Size of the file in bytes. url: type: - 'null' - string description: Signed URL to download the screenshot. Time-limited. reasoning: type: - 'null' - string description: AI reasoning at the time of capture, if recorded. created_at: type: string format: date-time description: When the screenshot was captured. description: A single screenshot captured during a task run. securitySchemes: BearerAuth: type: http description: Secret key (sk_live_...) scheme: bearer bearerFormat: JWT ````