---
title: "List policies"
method: GET
path: "/v1/workspaces/{workspaceId}/policies"
---

# List policies

`GET /v1/workspaces/{workspaceId}/policies`

## Path parameters

- `workspaceId` string, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

Paginated list of items

- object
  - `items` Policy[], required
    - `createdAt` string, required
    - `description` string
    - `enabled` boolean, required
    - `id` string, required
    - `metadata` object, required — Arbitrary metadata for the policy (record<string, string>)
    - `name` string, required
    - `priority` integer, required
    - `rules` PolicyRule[], required
      - `anyApproval` AnyApprovalRule
        - `minApprovals` integer, required
      - `createdAt` string, required
      - `deploymentDependency` DeploymentDependencyRule
        - `dependsOn` string, required — CEL expression to match upstream deployment(s) that must have a successful release before this deployment can proceed. The expression can reference both deployment properties (deployment.id, deployment.name, deployment.slug, deployment.metadata) and the currently deployed version properties (version.id, version.tag, version.name, version.status, version.metadata, version.createdAt). For example: deployment.name == 'db-migration' && version.tag.startsWith('v2.').
      - `deploymentWindow` DeploymentWindowRule
        - `allowWindow` boolean, required — If true, deployments are only allowed during the window. If false, deployments are blocked during the window (deny window)
        - `durationMinutes` integer, required — Duration of each deployment window in minutes
        - `rrule` string, required — RFC 5545 recurrence rule defining when deployment windows start (e.g., FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9)
        - `timezone` string — IANA timezone for the rrule (e.g., America/New_York). Defaults to UTC if not specified
      - `environmentProgression` EnvironmentProgressionRule
        - `dependsOnEnvironmentSelector` string, required — CEL expression to match the environment(s) that must have a successful release before this environment can proceed.
        - `maximumAgeHours` integer — Maximum age of dependency deployment before blocking progression (prevents stale promotions)
        - `minimumSoakTimeMinutes` integer — Minimum time to wait after the depends on environment is in a success state before the current environment can be deployed. Defaults to 0 if not provided.
        - `minimumSuccessPercentage` number, float
        - `requireVerificationPassed` boolean — If true, jobs must also have passed verification to count toward the success percentage
        - `successStatuses` JobStatus[]
      - `gradualRollout` GradualRolloutRule
        - `rolloutType` 'linear' | 'linear-normalized', required — Strategy for scheduling deployments to release targets. "linear": Each target is deployed at a fixed interval of timeScaleInterval seconds. "linear-normalized": Deployments are spaced evenly so that the last target is scheduled at or before timeScaleInterval seconds. See rolloutType algorithm documentation for details.
        - `timeScaleInterval` integer, required — Base time interval in seconds used to compute the delay between deployments to release targets.
      - `id` string, required
      - `planValidationOpa` PlanValidationOpaRule
        - `description` string
        - `name` string, required — Human-readable rule name; used in check output to identify which rule produced a violation.
        - `rego` string, required — Rego v1 source code. Must define a `deny` rule set following the Conftest convention (deny contains msg if { ... }).
      - `policyId` string, required
      - `retry` RetryRule
        - `backoffSeconds` integer — Minimum seconds to wait between retry attempts. If null, retries are allowed immediately after job completion.
        - `backoffStrategy` 'linear' | 'exponential' — Backoff strategy: "linear" uses constant backoffSeconds delay, "exponential" doubles the delay with each retry (backoffSeconds * 2^(attempt-1)).
        - `maxBackoffSeconds` integer — Maximum backoff time in seconds (cap for exponential backoff). If null, no maximum is enforced.
        - `maxRetries` integer, required — Maximum number of retries allowed. 0 means no retries (1 attempt total), 3 means up to 4 attempts (1 initial + 3 retries).
        - `retryOnStatuses` JobStatus[] — Job statuses that count toward the retry limit. If null or empty, defaults to ["failure", "invalidIntegration", "invalidJobAgent"] for maxRetries > 0, or ["failure", "invalidIntegration", "invalidJobAgent", "successful"] for maxRetries = 0. Cancelled and skipped jobs never count by default (allows redeployment after cancellation). Example: ["failure", "cancelled"] will only count failed/cancelled jobs.
      - `verification` VerificationRule
        - `metrics` VerificationMetricSpec[], required — Metrics to verify
          - `count` integer, required — Number of measurements to take
          - `failureCondition` string — CEL expression to evaluate measurement failure (e.g., "result.statusCode == 500"), if not provided, a failure is just the opposite of the success condition
          - `failureThreshold` integer — Stop after this many consecutive failures (0 = no limit)
          - `intervalSeconds` integer, required — Interval between measurements in seconds
          - `name` string, required — Name of the verification metric
          - `provider` union, required
            - HTTPMetricProvider
              - …
            - SleepMetricProvider
              - …
            - DatadogMetricProvider
              - …
            - PrometheusMetricProvider
              - …
            - TerraformCloudRunMetricProvider
              - …
          - `successCondition` string, required — CEL expression to evaluate measurement success (e.g., "result.statusCode == 200")
          - `successThreshold` integer — Minimum number of consecutive successful measurements required to consider the metric successful
        - `triggerOn` 'jobCreated' | 'jobStarted' | 'jobSuccess' | 'jobFailure' — When to trigger verification
      - `versionCooldown` VersionCooldownRule
        - `intervalSeconds` integer, required — Minimum time in seconds that must pass since the currently deployed (or in-progress) version was created before allowing another deployment. This enables batching of frequent upstream releases into periodic deployments.
      - `versionSelector` VersionSelectorRule
        - `description` string — Human-readable description of what this version selector does. Example: "Only deploy v2.x versions to staging environments"
        - `selector` string, required — CEL expression to select which versions are eligible for deployment.
    - `selector` string, required — CEL expression for matching release targets. Use "true" to match all targets.
    - `workspaceId` string, required
  - `limit` integer, required — Maximum number of items returned
  - `offset` integer, required — Number of items skipped
  - `total` integer, required — Total number of items available

---

[API](https://skmtc.net/ctrlplanedev/apis/ctrlplane-api.md) · [All operations](https://skmtc.net/ctrlplanedev/apis/ctrlplane-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ctrlplanedev/ctrlplane-api/versions/156e0d264995/schema)