---
title: "List Workflows"
method: GET
path: "/v1/workflows"
tags: ["workflows"]
---

# List Workflows

`GET /v1/workflows`

List all workflows for the authenticated organization.

Supports pagination and returns workflows ordered by updated_at descending.

Use `tag_ids` to filter workflows that have ALL specified tags (AND logic).
Use `include=tags,post_run_checks` to include related workflow resources.
Legacy `include_tags=true` remains supported, but `include` wins when both are provided.

## Query parameters

- `search` string, nullable — Search workflows by id or name (case-insensitive substring match)
- `created_at_from` string, date-time, nullable — Filter workflows created at or after this ISO timestamp (UTC)
- `created_at_to` string, date-time, nullable — Filter workflows created at or before this ISO timestamp (UTC)
- `updated_at_from` string, date-time, nullable — Filter workflows updated at or after this ISO timestamp (UTC)
- `updated_at_to` string, date-time, nullable — Filter workflows updated at or before this ISO timestamp (UTC)
- `tag_ids` string, nullable — Comma-separated list of tag UUIDs. Returns workflows with ALL specified tags (AND logic).
- `include_tags` boolean — Include tags in the response
- `include` string, nullable — Comma-separated list of related resources to include. Allowed values: tags, post_run_checks. If provided, overrides legacy include_tags.
- `skip` integer
- `limit` integer

## Response `200`

Successful Response

- PaginatedResponseWithIncludesWorkflowResponse
  - `items` WorkflowResponse[], required
    - `name` string, nullable
    - `main_prompt` string, required
    - `input_schema` string, nullable — JSON schema for validating merged run inputs. Sensitive root keys are exposed with a '$' prefix in schema validation (for example sensitive_input_values.api_key -> '$api_key').
    - `output_schema` string, nullable — JSON schema for output data transformation
    - `includes_file_exports` boolean — Enable AI-based file export detection
    - `is_webhooks_enabled` boolean — Send webhook on run completion
    - `terminal_command_allowlist` string[], nullable — Optional workflow-level allowlist for execute_terminal_command. When set, the agent may only run commands that exactly match one of the approved command templates.
    - `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).
    - `post_run_check_failure_cleanup_prompt` string, nullable — Optional workflow-level cleanup prompt that runs when any post-run check fails during a session or chain.
    - `id` string, uuid, required
    - `user_id` string, uuid, nullable
    - `organization_id` string, nullable
    - `includes_input_variables` boolean
    - `workflow_metadata` WorkflowInternalMetadata — Backend workflow metadata exposed read-only for internal observability.
      - `has_unaddressed_error` boolean, nullable — True when at least one run has failed and remains unaddressed.
      - `last_errored_run_start` string, date-time, nullable — Start timestamp of the most recent errored/task_failed run.
      - `last_errored_run_uuid` string, uuid, nullable — Run UUID of the most recent errored/task_failed run.
    - `old_versions` object[], nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `tags` WorkflowTagResponse[], nullable — Tags assigned to this workflow
      - `name` string, required
      - `description` string, nullable
      - `emoji` string, nullable
      - `color` string, nullable
      - `group_id` string, uuid, nullable — Optional group for mutual exclusivity
      - `id` string, uuid, required
      - `organization_id` string, required
      - `order` integer, required
      - `is_archived` boolean
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `workflow_count` integer, nullable — Number of workflows with this tag (returned in list endpoint)
      - `group` WorkflowTagGroupResponse — Workflow tag group response schema
        - `name` string, required
        - `description` string, nullable
        - `emoji` string, nullable
        - `color` string, nullable
        - `id` string, uuid, required
        - `organization_id` string, required
        - `order` integer, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
    - `post_run_checks` WorkflowPostRunCheckResponse[], nullable — Post-run checks assigned to this workflow.
      - `name` string, required
      - `description` string, nullable
      - `type` 'run_attachment_exists' | 'run_attachment_image_check' | 'output_data_passes_schema_validation' | 'output_data_agentic_check', required
      - `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 — Optional ModelConfiguration id override for agentic post-run checks.
      - `id` string, uuid, required
      - `organization_id` string, required
      - `user_id` string, uuid, nullable
      - `order` integer, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
  - `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/versions/830d2f48963d/schema)