--- updatedAt: 2026-05-28T08:16:45.000Z agentTools: projectIndex: https://docs.scalr.io/llms.txt --- # List Policy Groups This endpoint returns a list of [policy groups](/docs/policy-governance#open-policy-agent). # OpenAPI definition ```json { "components": { "schemas": { "PolicyGroup": { "description": "A policy group represents the collection of [OPA](/docs/policy-governance#open-policy-agent) policies stored in a VCS\nrepository.\n\nWhen [linked to an environment](/docs/assign-policies),\nthe policy group will participate in the policy check phase of every run in that environment.", "properties": { "attributes": { "properties": { "common-functions-folder": { "description": "An absolute path from the repository root to the folder that contains common rego functions.", "maxLength": 255, "nullable": true, "type": "string" }, "created-at": { "description": "Date/Time the policy group was created.", "format": "date-time", "readOnly": true, "type": "string" }, "error-message": { "description": "This field contains the error description when the group's status is `errored`.", "nullable": true, "readOnly": true, "type": "string" }, "execute-as": { "default": "policy_check", "description": "The stage of the run to evaluate the policy group.", "enum": [ "pre_plan_check", "policy_check" ], "type": "string" }, "is-enforced": { "default": false, "description": "Indicates whether the policy group is enforced in all environments.", "type": "boolean" }, "name": { "description": "The policy group name must be unique within the account and contain only letters, numbers, dashes", "maxLength": 100, "type": "string" }, "opa-version": { "description": "The version of Open Policy Agent to use for the policy evaluation.\n\nIf omitted, the system default version is assigned.", "type": "string" }, "status": { "description": "Policy group current status.\n\n* `fetching` - waiting for policies to be synchronized with VCS.\n* `active` - synchronization completed, policy group is ready.\n* `errored` - synchronization has failed. Attribute `error-message` contains the details.", "enum": [ "fetching", "active", "errored" ], "readOnly": true, "type": "string" }, "vcs-repo": { "properties": { "branch": { "description": "Branch of a repository the policy group is associated with.\nIf omitted, the repository default branch will be used.", "nullable": true, "type": "string" }, "identifier": { "description": "A reference to your VCS repository.\n\nFor GitHub, GitHub Enterprise and GitLab the format is `/`.\nFor Azure DevOps Services the format is `//`.", "type": "string" }, "path": { "default": "", "description": "The sub-directory of the VCS repository where OPA policies are stored.\nThe `scalr-policy.hcl` file must exist in this directory.\nFiles and directories outside this directory will be ignored during a sync from VCS,\nand changing them won't trigger a policy group update.\n\nIf omitted or submitted as an empty string, this defaults to the repository's root.", "nullable": true, "type": "string" } }, "required": [ "identifier" ], "type": "object" } }, "required": [ "name", "vcs-repo" ], "type": "object" }, "id": { "readOnly": true, "type": "string" }, "links": { "properties": { "self": { "readOnly": true, "type": "string" } }, "readOnly": true, "type": "object" }, "relationships": { "properties": { "account": { "description": "The account this policy group belongs to.", "properties": { "data": { "properties": { "id": { "type": "string" }, "type": { "enum": [ "accounts", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "environments": { "description": "List of environments this policy group is linked to.", "properties": { "data": { "items": { "properties": { "id": { "type": "string" }, "type": { "enum": [ "environments", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "nullable": true, "type": "array" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "policies": { "description": "List of OPA policies this group contains.", "properties": { "data": { "items": { "properties": { "id": { "type": "string" }, "type": { "enum": [ "policies", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "nullable": true, "type": "array" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "vcs-provider": { "description": "The policy group's VCS provider.", "properties": { "data": { "properties": { "id": { "type": "string" }, "type": { "enum": [ "vcs-providers", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "vcs-revision": { "description": "The Git commit information when the policy group was fetched from VCS.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "vcs-revisions", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" } }, "required": [ "vcs-provider", "account" ], "type": "object" }, "type": { "enum": [ "policy-groups" ], "type": "string" } }, "required": [ "type", "attributes", "relationships" ], "type": "object" }, "PolicyGroupListingDocument": { "description": "JSON:API Document Listing\n\nsee: https://jsonapi.org/format/#document-structure", "properties": { "data": { "items": { "$ref": "#/components/schemas/PolicyGroup" }, "type": "array" }, "included": { "items": { "type": "object" }, "readOnly": true, "type": "array" }, "links": { "additionalProperties": { "type": "string" }, "readOnly": true, "type": "object" }, "meta": { "readOnly": true, "type": "object" } }, "type": "object" } }, "securitySchemes": { "API-Key": { "scheme": "bearer", "type": "http" } } }, "info": { "description": "Scalr IACP API", "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "title": "Scalr IACP API", "version": "unversioned" }, "openapi": "3.0.0", "paths": { "/policy-groups": { "get": { "description": "This endpoint returns a list of [policy groups](/docs/policy-governance#open-policy-agent).", "operationId": "list_policy_groups", "parameters": [ { "description": "Filter by policy group id", "in": "query", "name": "filter[policy-group]", "required": false, "schema": { "type": "string" } }, { "description": "Environment filter", "in": "query", "name": "filter[environment]", "required": false, "schema": { "type": "string" } }, { "description": "The ID of the software version", "in": "query", "name": "filter[software-version]", "required": false, "schema": { "type": "string" } }, { "description": "The ID of the VCS provider", "in": "query", "name": "filter[vcs-provider]", "required": false, "schema": { "type": "string" } }, { "description": "The policy group name filter.", "in": "query", "name": "filter[name]", "required": false, "schema": { "type": "string" } }, { "description": "The comma-separated list of relationship paths.", "explode": false, "in": "query", "name": "include", "required": false, "schema": { "items": { "enum": [ "account", "policies", "vcs-provider", "vcs-revision" ], "type": "string" }, "type": "array" } }, { "description": "Query string", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The comma-separated list of attributes.", "explode": false, "in": "query", "name": "sort", "required": false, "schema": { "items": { "enum": [ "account", "created-at", "name", "status" ], "type": "string" }, "type": "array" } }, { "description": "Page number", "in": "query", "name": "page[number]", "required": false, "schema": { "type": "string" } }, { "description": "Page size", "in": "query", "name": "page[size]", "required": false, "schema": { "type": "string" } }, { "description": "The value of the fields[resource-type] parameter is a comma-separated list that refers to the name of the fields to be returned for the resource. An empty value indicates that no fields should be returned.", "explode": true, "in": "query", "name": "fields", "required": false, "schema": { "properties": { "accounts": { "description": "The comma-separated list of fields to return in response for Account resource.", "type": "string" }, "policies": { "description": "The comma-separated list of fields to return in response for Policy resource.", "type": "string" }, "policy-groups": { "description": "The comma-separated list of fields to return in response for PolicyGroup resource.", "type": "string" }, "vcs-providers": { "description": "The comma-separated list of fields to return in response for VcsProvider resource.", "type": "string" }, "vcs-revisions": { "description": "The comma-separated list of fields to return in response for VcsRevision resource.", "type": "string" } }, "type": "object" }, "style": "deepObject" } ], "responses": { "200": { "content": { "application/vnd.api+json": { "examples": { "default": { "value": "{\n \"data\": [\n {\n \"attributes\": {\n \"error-message\": null,\n \"name\": \"Tags\",\n \"opa-version\": \"0.29.4\",\n \"status\": \"active\",\n \"vcs-repo\": {\n \"branch\": \"master\",\n \"identifier\": \"my_org/repo\",\n \"path\": \"policies/tags\"\n }\n },\n \"id\": \"pgrp-svsu1tn68mhevuo\",\n \"links\": {\n \"self\": \"https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-svsu1tn68mhevuo\"\n },\n \"relationships\": {\n \"account\": {\n \"data\": {\n \"id\": \"acc-svrcncgh453bi8g\",\n \"type\": \"accounts\"\n }\n },\n \"environments\": {\n \"data\": [\n {\n \"id\": \"env-svrcnchebt61e30\",\n \"type\": \"environments\"\n },\n {\n \"id\": \"env-svrdqa8d7mhaimo\",\n \"type\": \"environments\"\n }\n ]\n },\n \"policies\": {\n \"data\": [\n {\n \"id\": \"policy-ta3cb9im2kdck4g\",\n \"type\": \"policies\"\n },\n {\n \"id\": \"policy-tmttegdtd1rg0fg\",\n \"type\": \"policies\"\n }\n ]\n },\n \"vcs-provider\": {\n \"data\": {\n \"id\": \"vcs-svsmeap82s0tsho\",\n \"type\": \"vcs-providers\"\n }\n },\n \"vcs-revision\": {\n \"data\": {\n \"id\": \"vrb-svsu1tn54f6brfg\",\n \"type\": \"vcs-revisions\"\n }\n },\n \"workspaces\": {\n \"data\": [\n {\n \"id\": \"ws-tmtt98uuhs7n7do\",\n \"type\": \"workspaces\"\n },\n {\n \"id\": \"ws-tmtt9e4fn037nq8\",\n \"type\": \"workspaces\"\n },\n {\n \"id\": \"ws-tmtt9ir5ra2ta6o\",\n \"type\": \"workspaces\"\n }\n ]\n }\n },\n \"type\": \"policy-groups\"\n },\n {\n \"attributes\": {\n \"error-message\": \"scalr-policy.hcl not found in repository\",\n \"name\": \"Instance types\",\n \"opa-version\": \"0.29.4\",\n \"status\": \"errored\",\n \"vcs-repo\": {\n \"branch\": \"master\",\n \"identifier\": \"Scalr/tf-revizor-fixtures\",\n \"path\": \"policies/instances\"\n }\n },\n \"id\": \"pgrp-svsu2pkubpob58o\",\n \"links\": {\n \"self\": \"https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-svsu2pkubpob58o\"\n },\n \"relationships\": {\n \"account\": {\n \"data\": {\n \"id\": \"acc-svrcncgh453bi8g\",\n \"type\": \"accounts\"\n }\n },\n \"environments\": null,\n \"policies\": null,\n \"vcs-provider\": {\n \"data\": {\n \"id\": \"vcs-svsmeap82s0tsho\",\n \"type\": \"vcs-providers\"\n }\n },\n \"vcs-revision\": {\n \"data\": {\n \"id\": \"vrb-svsu2pkt28f32go\",\n \"type\": \"vcs-revisions\"\n }\n },\n \"workspaces\": null\n },\n \"type\": \"policy-groups\"\n }\n ],\n \"included\": null,\n \"links\": {\n \"first\": \"https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20\",\n \"last\": \"https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20\",\n \"next\": null,\n \"prev\": null,\n \"self\": \"https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20\"\n },\n \"meta\": {\n \"pagination\": {\n \"current-page\": 1,\n \"next-page\": null,\n \"prev-page\": null,\n \"total-count\": 2,\n \"total-pages\": 1\n }\n }\n}" } }, "schema": { "$ref": "#/components/schemas/PolicyGroupListingDocument" } } }, "description": "Success." }, "403": { "description": "User unauthorized to perform this action." }, "4XX": { "description": "Client error." }, "5XX": { "description": "Server error." } }, "summary": "List Policy Groups", "tags": [ "policy-groups" ], "x-mcp-tool": true, "x-resource": "PolicyGroup", "x-service": "tf-api" } } }, "security": [ { "API-Key": [] } ], "servers": [ { "url": "https://{Domain}/api/iacp/v3", "variables": { "Domain": { "default": "example.scalr.io", "description": "Domain where Scalr is hosted" } } } ] } ``` # Sibling pages * [Create a Policy Group](https://docs.scalr.io/scalr/reference/create_policy_group.md) * [Delete a Policy Group](https://docs.scalr.io/scalr/reference/delete_policy_group.md) * [Get a Policy Group](https://docs.scalr.io/scalr/reference/get_policy_group.md) * [Update a Policy Group](https://docs.scalr.io/scalr/reference/update_policy_group.md) * [List of policy group check results for pull requests.](https://docs.scalr.io/scalr/reference/list_pull_request_policy_check_results.md) * [Resync a Policy Group](https://docs.scalr.io/scalr/reference/resync_policy_group.md)