> ## 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 workflow run > Returns a single workflow run by ID, including each step's status, output, and task runs. ## OpenAPI ````yaml /api-reference/v2.json get /workflow-runs/{workflow_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 description: >- Agents are the AI workers that execute tasks against sources. Create and manage the agents in your organization. - name: Components description: >- Embeddable UI components. Create short-lived session tokens for the Auth Component. - name: Credentials description: >- Credentials store the login details an agent uses at a source. Values are tokenized at rest and never returned in plaintext. - name: Event Destinations description: >- Where Deck delivers events: webhooks, SQS, Kinesis, S3, or EventBridge. Manage destinations and inspect delivery attempts. - name: Events description: >- Immutable records of things that happened in your organization, such as a task run completing or a credential being verified. - name: Sessions description: >- Sessions are agent sandbox lifetimes. A session is created for each task run (or explicitly) and counts toward your concurrency limit. - name: Sources description: >- Sources are the websites and portals agents work against. Register, inspect, reset, and delete them. - name: Storage description: >- Files produced by task runs: downloaded documents, exports, and extraction results. - name: Task Runs description: >- A task run is one execution of a task. Inspect status and output, retrieve files and screenshots, cancel runs, and answer interaction requests. - name: Tasks description: >- Tasks define reusable units of work for an agent: a goal, an input schema, and an output schema. Run them against sources with credentials. - name: Test description: Connectivity check for your API key. - name: Triggers description: Triggers run tasks automatically on a schedule or in response to events. - name: Workflows - name: Workflow Runs paths: /workflow-runs/{workflow_run_id}: get: tags: - Workflow Runs summary: Retrieve a workflow run description: >- Returns a single workflow run by ID, including each step's status, output, and task runs. operationId: getWorkflowRun parameters: - name: workflow_run_id in: path required: true schema: type: string pattern: ^wrun_ example: wrun_AbC123xYz456 description: Unique identifier for the workflow run (prefixed with `wrun_`). - name: include in: query schema: type: string description: >- Comma-separated list of additional fields to include on each `task_runs` entry. 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/WorkflowRunResponse' application/json: schema: $ref: '#/components/schemas/WorkflowRunResponse' text/json: schema: $ref: '#/components/schemas/WorkflowRunResponse' '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' '429': description: >- Too many requests — the organization-wide API rate limit was exceeded (`rate_limit_exceeded`). Retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: WorkflowRunResponse: type: object required: - id - object - workflow_id - status - result - runtime_ms - session_id - trigger_id - steps - errors - created_at - updated_at properties: id: type: string pattern: ^wrun_ example: wrun_AbC123xYz456 description: Unique identifier for the workflow run, prefixed with `wrun_`. object: type: string description: Always `workflow_run`. workflow_id: type: string pattern: ^wflo_ example: wflo_AbC123xYz456 description: The workflow that was run. status: type: string enum: - queued - running - paused - completed - failed - canceling - canceled description: >- Lifecycle state. `paused` means the current step is waiting on external input; the step's own status carries the reason. result: type: - 'null' - string description: >- Outcome once terminal: `success` only when every task run succeeded, `failure` if any failed, `unknown` otherwise. `null` while running and for a canceled run. runtime_ms: type: - 'null' - integer format: int64 description: >- Milliseconds from the first step's start until the run reached a terminal status, excluding time spent queued. `null` until terminal. session_id: type: - 'null' - string description: >- The session every step of this run executes in. Prefixed with `sess_`. Assigned when the run is created through the API, or when a trigger-created run is admitted, so `null` while such a run is queued. trigger_id: type: - 'null' - string description: >- The trigger that created this run. Prefixed with `trg_`. `null` for runs created through the API. steps: type: array items: $ref: '#/components/schemas/WorkflowRunStepResponse' description: Per-step state, in definition order. errors: type: - 'null' - array items: $ref: '#/components/schemas/WorkflowRunError' description: >- Error objects, each naming its `step`, when the run failed. `null` otherwise. created_at: type: string format: date-time example: '2026-06-18T00:00:00Z' updated_at: type: string format: date-time example: '2026-06-18T00:00:00Z' request_id: type: string description: >- Unique identifier for the API request. Include this when contacting support. description: Workflow run object. 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. WorkflowRunStepResponse: type: object required: - name - type - status - output properties: name: type: string description: The step's name, matching the definition. type: type: string enum: - task - for_each description: '`task` or `for_each`.' status: type: string description: >- The underlying task run's status (`queued`, `running`, `interaction_required`, `review_required`, `completed`, `failed`, `canceling`, `canceled`), plus `skipped` when the step's `if` evaluated false. A `for_each` aggregates its items. output: oneOf: - type: 'null' - $ref: '#/components/schemas/JsonElement' description: >- What references to this step resolve to: the task's output, or the ordered array of per-item outputs for a `for_each`. `null` until completion, and for a skipped step. task_runs: type: - 'null' - array items: $ref: '#/components/schemas/WorkflowRunTaskRunResponse' description: >- The task runs this step produced, in order: one for a `task` step, one per item processed for a `for_each`, none for a skipped step. Returned on single-run responses; omitted from list responses. description: One step's state within a workflow run. WorkflowRunError: type: object required: - type - code - message properties: type: type: string description: Error category (e.g. `source`, `auth`, `task`). code: type: string description: Machine-readable error code. 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. Omitted otherwise. step: type: - 'null' - string description: The step that caused the run to fail. description: >- A standard Deck error object plus the `step` that caused the failure. The same error, without `step`, appears on that step's `task_runs` entry. 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. JsonElement: description: Arbitrary JSON value. WorkflowRunTaskRunResponse: type: object required: - task_run_id - status - result - created_at - runtime_ms - errors properties: task_run_id: type: string pattern: ^trun_ example: trun_AbC123xYz456 description: >- The task run this entry summarizes. `GET /v2/task-runs/{run_id}` is the authoritative record. status: type: string description: The task run's status. result: type: - 'null' - string description: '`success`, `failure`, or `unknown`. `null` until terminal.' created_at: type: string format: date-time example: '2026-06-18T00:00:00Z' description: >- When the task run was created. Because steps run sequentially, this is when the step or item started. runtime_ms: type: - 'null' - integer format: int32 description: >- Execution time in milliseconds. `null` until terminal, and for a run that failed before it started. errors: type: - 'null' - array items: $ref: '#/components/schemas/TaskRunError' description: Errors for this run when it failed. `null` otherwise. item: oneOf: - type: 'null' - $ref: '#/components/schemas/JsonElement' description: '`for_each` only. The input item this run processed.' input: oneOf: - type: 'null' - $ref: '#/components/schemas/JsonElement' description: >- The resolved input this run received, with references substituted. Returned only when `include=input` is requested. storage: type: - 'null' - array items: $ref: '#/components/schemas/TaskRunStorageItem' description: >- Files captured during this run, each with inline extraction (if any). Returned only when `include=storage` is requested. artifacts: oneOf: - type: 'null' - $ref: '#/components/schemas/TaskRunArtifactData' description: >- Screenshots for this run. Returned only when `include=artifacts` is requested. description: A compact summary of one task run a step produced. 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_`. pattern: ^stor_ example: stor_AbC123xYz456 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. example: '2026-08-24T12:00:00Z' 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. required: - screenshots 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. example: '2026-08-24T12:00:00Z' description: A single screenshot captured during a task run. securitySchemes: BearerAuth: type: http description: Secret key (sk_live_...) scheme: bearer bearerFormat: JWT ````