---
title: "List Runs"
method: GET
path: "/v1/runs"
tags: ["runs"]
---

# List Runs

`GET /v1/runs`

List all runs for the authenticated organization.

Supports pagination and filtering by workflow, machine, and status.
Returns runs with their associated workflow and machine data.

Use the `include` parameter to fetch related resources in the response.
Related resources are returned in the `included` array following the JSON:API pattern.
Resources are deduplicated across all items in the list.

## Query parameters

- `workflow_id` string, uuid, nullable — Filter by workflow ID
- `machine_id` string, uuid, nullable — Filter by machine ID
- `session_id` string, uuid, nullable — Filter by session ID
- `status` 'scheduling' | 'running' | 'running_checks' | 'success' | 'cancelled' | 'task_failed' | 'error'
- `created_at_from` string, date-time, nullable — Filter runs created at or after this ISO timestamp (UTC)
- `created_at_to` string, date-time, nullable — Filter runs created at or before this ISO timestamp (UTC)
- `sort_mode` 'activity' | 'created_at_desc'
- `search` string, nullable — Search runs by id, input_values, output_data, error, session_alias (case-insensitive substring match)
- `deep_search` boolean — If true, also search run_message_history (slower but more comprehensive)
- `fields` RunField[], nullable — Optional list of fields to include per run. Always includes: id, workflow_id, machine_id, status, created_at. Provide multiple 'fields=' params to include more.
- `include` string, nullable — Comma-separated list of related resources to include. Allowed values: workflow, machine, machine.pools. Example: include=workflow,machine
- `skip` integer
- `limit` integer

## Response `200`

Successful Response

- PaginatedResponseWithIncludesRunResponse
  - `items` RunResponse[], required
    - `workflow_id` string, uuid, required
    - `machine_id` string, uuid, nullable, required
    - `id` string, uuid, required
    - `user_id` string, uuid, nullable
    - `organization_id` string, nullable
    - `is_priority` boolean
    - `status` 'scheduling' | 'running' | 'running_checks' | 'success' | 'cancelled' | 'task_failed' | 'error', required
    - `error` string[], nullable
    - `output_data` object, nullable
    - `input_attachment_ids` string[], nullable
    - `output_attachment_ids` string[], nullable
    - `run_message_history` object[], nullable
    - `input_values` object, nullable
    - `main_prompt` string, nullable — Per-run prompt override used for execution. Null means the run falls back to the workflow's current main_prompt.
    - `model_metadata` WorkflowModelMetadata — JSONB-backed workflow model configuration metadata. Stored on the Workflow row as `model_metadata` to avoid adding many FK columns. All fields are optional; when missing/null, the system falls back to Cyberdesk defaults.
      - `main_agent_model_id` string, uuid, nullable — ModelConfiguration.id used for the main agent. Null → Cyberdesk default.
      - `cache_detection_model_id` string, uuid, nullable — ModelConfiguration.id used for cache detection. Null → Cyberdesk default.
      - `fallback_model_1_id` string, uuid, nullable — ModelConfiguration.id used as fallback 1 (global across agents).
      - `fallback_model_2_id` string, uuid, nullable — ModelConfiguration.id used as fallback 2 (global across agents).
    - `pool_ids` string[], nullable
    - `sensitive_input_aliases` object, nullable
    - `usage_metadata` object, nullable — Arbitrary usage/billing metadata captured during a run (schema is flexible)
    - `post_run_checks` RunPostRunCheckSnapshot[], nullable — Version-tolerant snapshot/results for the run's post-run checks.
      - `id` string, uuid, nullable
      - `post_run_check_id` string, uuid, nullable
      - `snapshot_version` integer, nullable
      - `name` string, nullable
      - `description` string, nullable
      - `type` 'run_attachment_exists' | 'run_attachment_image_check' | 'output_data_passes_schema_validation' | 'output_data_agentic_check'
      - `order` integer, nullable
      - `file_target_mode` 'exact' | 'regex' | 'loop_items'
      - `file_names` string[], nullable
      - `file_name_regex` string, nullable
      - `expected_match_count` integer, nullable
      - `expected_match_count_ref` string, nullable
      - `loop_input` string, nullable
      - `loop_item_filename_template` string, nullable
      - `allow_missing_attachments` boolean
      - `check_prompt` string, nullable
      - `model` string, uuid, nullable
      - `status` 'pending' | 'running' | 'success' | 'failed' | 'infra_error' | 'cancelled', required
      - `started_at` string, date-time, nullable
      - `ended_at` string, date-time, nullable
      - `error_message` string, nullable
      - `messages` string[], nullable
      - `matched_filenames` string[], nullable
    - `session_id` string, uuid, nullable
    - `session_alias` string, nullable
    - `release_session_after` boolean, nullable
    - `created_at` string, date-time, required
    - `started_at` string, date-time, nullable
    - `ended_at` string, date-time, nullable
  - `total` integer, required
  - `skip` integer, required
  - `limit` integer, required
  - `included` IncludedResource[], nullable — Related resources requested via the `include` query parameter
    - `type` string, required — Resource type (e.g., 'workflow', 'machine', 'pool')
    - `id` string, uuid, required — Resource UUID

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud.md) · [All operations](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cyberdesk-hq/cyberdesk-cloud/revisions/830d2f48963d/schema)