---
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.
      - `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)
        - `minimumSockTimeMinutes` integer — Minimum time to wait after the depends on environment is in a success state before the current environment can be deployed
        - `minimumSuccessPercentage` number, float
        - `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
      - `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

## Changes

- **2026-03-12** `95ad4756775e` — 2 breaking, 2 info
  - the `items/items/rules/items/environmentProgression/dependsOnEnvironmentSelector` response's property type/format changed from ``/`` to `string`/`` for status `200`
  - the `items/items/rules/items/versionSelector/selector` response's property type/format changed from ``/`` to `string`/`` for status `200`
  - removed `#/components/schemas/JsonSelector, #/components/schemas/CelSelector` from the `items/items/rules/items/environmentProgression/dependsOnEnvironmentSelector` response property `oneOf` list for the response status `200`
  - removed `#/components/schemas/JsonSelector, #/components/schemas/CelSelector` from the `items/items/rules/items/versionSelector/selector` response property `oneOf` list for the response status `200`
- **2026-02-20** `b9cba5428947` — 1 info
  - added the optional property `items/items/rules/items/versionSelector` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/ctrlplanedev/apis/ctrlplane-api/changes/v1/workspaces/:workspaceId/policies/get.md)

---

[API](https://skmtc.dev/ctrlplanedev/apis/ctrlplane-api.md) · [All operations](https://skmtc.dev/ctrlplanedev/apis/ctrlplane-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ctrlplanedev/ctrlplane-api/revisions/9228d89dddda/schema)