Skip to main content
Pulumi logo Pulumi logo
25.8K Contact us Sign in Dashboard Get started
  1. Docs
  2. Reference
  3. REST API Docs
  4. Policy Findings

Policy Findings

    List Policy Findings

    ▼
    POST /api/orgs/{orgName}/policy/findings

    Returns the policy Findings for an organization, with pagination and filtering via the grid request format. A Finding is one resource failing one policy, tracked with a triage state; it keeps the same id when it recurs or when the policy pack version changes. Each Finding includes the failing resource, the policy pack and policy that flagged it, the enforcement level (advisory or mandatory), severity, and triage status.

    Request Parameters

    • orgName string path required
      The organization name
    • closed boolean query optional
      If true, return closed Findings; if false or omitted, return active Findings

    Request Body

    Schema: AngularGridGetRowsRequest

    Responses

    200 OK
    Schema: ListPolicyIssuesResponse
    • policyIssues array[PolicyIssue] required
      The list of policy issues
    • ↳ id string required
      The unique identifier of the policy issue.
    • ↳ entityType enum required
      The type of entity this issue applies to.
      Values:
      stack — Stack
      insights-account — InsightsAccount
    • ↳ entityProject string required
      The project name (for stack entities) or parent Insights account name (for resource entities).
    • ↳ entityId string required
      The identifier of the entity this issue applies to.
    • ↳ stackVersion integer optional
      The stack version where the issue was detected.
    • ↳ resourceVersion integer optional
      The resource version where the issue was detected.
    • ↳ policyPack string required
      The name of the policy pack that produced this issue.
    • ↳ policyPackTag string required
      The tag of the policy pack version that produced this issue.
    • ↳ policyName string required
      The name of the policy that was violated.
    • ↳ resourceURN string required
      The URN of the resource that violated the policy.
    • ↳ resourceProvider string required
      The provider of the resource that violated the policy.
    • ↳ resourceType string required
      The type of the resource that violated the policy.
    • ↳ resourceName string required
      The name of the resource that violated the policy.
    • ↳ message string optional
      A human-readable message describing the policy violation.
    • ↳ observedAt string required
      The timestamp when the issue was first observed.
    • ↳ lastModified string optional
      The timestamp when the issue was last modified.
    • ↳ level string required
      The enforcement level of the policy (e.g. advisory, mandatory, disabled).
    • ↳ severity enum required
      The severity of the policy violation.
      Values:
      — Unspecified
      low — Low
      medium — Medium
      high — High
      critical — Critical
    • ↳ status enum required
      The current status of the policy issue.
      Values:
      open — Open
      in_progress — InProgress
      by_design — ByDesign
      fixed — Fixed
      ignored — Ignored
    • ↳ kind enum required
      The kind of policy issue (audit or preventative).
      Values: audit, preventative
    • ↳ priority enum required
      The priority level of the policy issue.
      Values: p0, p1, p2, p3, p4
    • ↳ assignedTo UserInfo optional
      The user the policy issue is assigned to.
    • ↳ policyGroupName string optional
      The name of the policy group this issue belongs to.
    • ↳ policyGroupType enum optional
      The type of the policy group this issue belongs to.
      Values: audit, preventative
    • groupData array[object] required
      Grouped data for policy issue aggregation
    • rowCount integer optional
      The total number of policy issue rows
    Errors: 400 Invalid filter parameters 404 Organization not found

    Get Policy Finding

    ▼
    GET /api/orgs/{orgName}/policy/findings/{findingId}

    Returns the details of a specific policy Finding, including the failing resource, the policy pack and policy that flagged it, the enforcement level (advisory or mandatory), severity, and the current triage status. A Finding is one resource failing one policy, tracked with a triage state; it keeps the same id when it recurs or when the policy pack version changes.

    Request Parameters

    • orgName string path required
      The organization name
    • findingId string path required
      The Finding identifier

    Responses

    200 OK
    Schema: GetPolicyIssueResponse
    • policyIssue PolicyIssue required
      The policy issue details
    • ↳ id string required
      The unique identifier of the policy issue.
    • ↳ entityType enum required
      The type of entity this issue applies to.
      Values:
      stack — Stack
      insights-account — InsightsAccount
    • ↳ entityProject string required
      The project name (for stack entities) or parent Insights account name (for resource entities).
    • ↳ entityId string required
      The identifier of the entity this issue applies to.
    • ↳ stackVersion integer optional
      The stack version where the issue was detected.
    • ↳ resourceVersion integer optional
      The resource version where the issue was detected.
    • ↳ policyPack string required
      The name of the policy pack that produced this issue.
    • ↳ policyPackTag string required
      The tag of the policy pack version that produced this issue.
    • ↳ policyName string required
      The name of the policy that was violated.
    • ↳ resourceURN string required
      The URN of the resource that violated the policy.
    • ↳ resourceProvider string required
      The provider of the resource that violated the policy.
    • ↳ resourceType string required
      The type of the resource that violated the policy.
    • ↳ resourceName string required
      The name of the resource that violated the policy.
    • ↳ message string optional
      A human-readable message describing the policy violation.
    • ↳ observedAt string required
      The timestamp when the issue was first observed.
    • ↳ lastModified string optional
      The timestamp when the issue was last modified.
    • ↳ level string required
      The enforcement level of the policy (e.g. advisory, mandatory, disabled).
    • ↳ severity enum required
      The severity of the policy violation.
      Values:
      — Unspecified
      low — Low
      medium — Medium
      high — High
      critical — Critical
    • ↳ status enum required
      The current status of the policy issue.
      Values:
      open — Open
      in_progress — InProgress
      by_design — ByDesign
      fixed — Fixed
      ignored — Ignored
    • ↳ kind enum required
      The kind of policy issue (audit or preventative).
      Values: audit, preventative
    • ↳ priority enum required
      The priority level of the policy issue.
      Values: p0, p1, p2, p3, p4
    • ↳ assignedTo UserInfo optional
      The user the policy issue is assigned to.
    • ↳ policyGroupName string optional
      The name of the policy group this issue belongs to.
    • ↳ policyGroupType enum optional
      The type of the policy group this issue belongs to.
      Values: audit, preventative
    • policy AppPolicy optional
      The policy definition that caused this issue. May be null if the policy has been deleted or is unavailable.
    • ↳ name string required
      Unique URL-safe name for the policy. This is unique to a specific version of a Policy Pack.
    • ↳ displayName string required
      The display name
    • ↳ description string required
      Description is used to provide more context about the purpose of the policy.
    • ↳ enforcementLevel enum required
      The enforcement level
      Values: advisory, mandatory, remediate, disabled
    • ↳ message string required
      Message is the message that will be displayed to end users when they violate this policy.
    • ↳ configSchema AppPolicyConfigSchema optional
      The JSON schema for the Policy’s configuration.
    • ↳ severity enum optional
      The severity of the policy.
      Values:
      — Unspecified
      low — Low
      medium — Medium
      high — High
      critical — Critical
    • ↳ framework AppPolicyComplianceFramework optional
      The compliance framework that this policy belongs to.
    • ↳ tags array[string] optional
      Tags associated with the policy.
    • ↳ remediationSteps string optional
      A description of the steps to take to remediate a policy violation.
    • ↳ url string optional
      A URL to more information about the policy.
    • policyPack RegistryPolicyPack optional
      The registry policy pack metadata. May be null if the policy pack is unavailable.
    • ↳ id string required
      ID is the unique identifier for this policy pack in the registry. This is a UUID that corresponds to the policy pack’s database ID.
    • ↳ source string required
      Source indicates where this policy pack is hosted (e.g., “private”, “pulumi”). Currently, only “private” policy packs are supported.
    • ↳ publisher string required
      Publisher is the organization or user that published this policy pack. This corresponds to the Pulumi organization name.
    • ↳ name string required
      Name is the unique identifier for this policy pack within the publisher’s namespace. Policy pack names must be URL-safe and unique per publisher.
    • ↳ version string required
      Version is the semantic version of this policy pack. This represents the latest or specific version being referenced.
    • ↳ displayName string required
      DisplayName is a human-readable name for this policy pack. This is typically more descriptive than the technical name.
    • ↳ accessLevel enum required
      AccessLevel is the client’s level of access to this policy pack.
      Values:
      full — Full
      Full access to a policy pack (view + use)
      view-only — ViewOnly
      Access to view a policy pack
      deny — Deny
      No access to a policy pack
    • ↳ enforcementLevels array[string] required
      EnforcementLevels are the client’s allowed enforcement levels for this policy pack.
    Errors: 404 Organization or Policy Finding not found

    Update Policy Finding

    ▼
    PATCH /api/orgs/{orgName}/policy/findings/{findingId}

    Updates a policy Finding’s triage status and other mutable fields. All body fields are optional — only provide the fields you want to update.

    • status: open, in_progress, or ignored (fixed and by_design cannot be set manually)
    • priority: p0, p1, p2, p3, or p4
    • assignedTo: username to assign the Finding to, or null to unassign

    Request Parameters

    • orgName string path required
      The organization name
    • findingId string path required
      The Finding identifier

    Request Body

    Schema: UpdatePolicyIssueRequest
    • assignedTo string optional
      The user to assign the policy issue to.
    • status enum optional
      The new status for the policy issue. Valid values: open, in_progress, ignored. Note: fixed and by_design cannot be set manually.
      Values:
      open — Open
      in_progress — InProgress
      by_design — ByDesign
      fixed — Fixed
      ignored — Ignored
    • priority enum optional
      The new priority for the policy issue.
      Values: p0, p1, p2, p3, p4

    Responses

    200 OK
    Schema: GetPolicyIssueResponse
    • policyIssue PolicyIssue required
      The policy issue details
    • ↳ id string required
      The unique identifier of the policy issue.
    • ↳ entityType enum required
      The type of entity this issue applies to.
      Values:
      stack — Stack
      insights-account — InsightsAccount
    • ↳ entityProject string required
      The project name (for stack entities) or parent Insights account name (for resource entities).
    • ↳ entityId string required
      The identifier of the entity this issue applies to.
    • ↳ stackVersion integer optional
      The stack version where the issue was detected.
    • ↳ resourceVersion integer optional
      The resource version where the issue was detected.
    • ↳ policyPack string required
      The name of the policy pack that produced this issue.
    • ↳ policyPackTag string required
      The tag of the policy pack version that produced this issue.
    • ↳ policyName string required
      The name of the policy that was violated.
    • ↳ resourceURN string required
      The URN of the resource that violated the policy.
    • ↳ resourceProvider string required
      The provider of the resource that violated the policy.
    • ↳ resourceType string required
      The type of the resource that violated the policy.
    • ↳ resourceName string required
      The name of the resource that violated the policy.
    • ↳ message string optional
      A human-readable message describing the policy violation.
    • ↳ observedAt string required
      The timestamp when the issue was first observed.
    • ↳ lastModified string optional
      The timestamp when the issue was last modified.
    • ↳ level string required
      The enforcement level of the policy (e.g. advisory, mandatory, disabled).
    • ↳ severity enum required
      The severity of the policy violation.
      Values:
      — Unspecified
      low — Low
      medium — Medium
      high — High
      critical — Critical
    • ↳ status enum required
      The current status of the policy issue.
      Values:
      open — Open
      in_progress — InProgress
      by_design — ByDesign
      fixed — Fixed
      ignored — Ignored
    • ↳ kind enum required
      The kind of policy issue (audit or preventative).
      Values: audit, preventative
    • ↳ priority enum required
      The priority level of the policy issue.
      Values: p0, p1, p2, p3, p4
    • ↳ assignedTo UserInfo optional
      The user the policy issue is assigned to.
    • ↳ policyGroupName string optional
      The name of the policy group this issue belongs to.
    • ↳ policyGroupType enum optional
      The type of the policy group this issue belongs to.
      Values: audit, preventative
    • policy AppPolicy optional
      The policy definition that caused this issue. May be null if the policy has been deleted or is unavailable.
    • ↳ name string required
      Unique URL-safe name for the policy. This is unique to a specific version of a Policy Pack.
    • ↳ displayName string required
      The display name
    • ↳ description string required
      Description is used to provide more context about the purpose of the policy.
    • ↳ enforcementLevel enum required
      The enforcement level
      Values: advisory, mandatory, remediate, disabled
    • ↳ message string required
      Message is the message that will be displayed to end users when they violate this policy.
    • ↳ configSchema AppPolicyConfigSchema optional
      The JSON schema for the Policy’s configuration.
    • ↳ severity enum optional
      The severity of the policy.
      Values:
      — Unspecified
      low — Low
      medium — Medium
      high — High
      critical — Critical
    • ↳ framework AppPolicyComplianceFramework optional
      The compliance framework that this policy belongs to.
    • ↳ tags array[string] optional
      Tags associated with the policy.
    • ↳ remediationSteps string optional
      A description of the steps to take to remediate a policy violation.
    • ↳ url string optional
      A URL to more information about the policy.
    • policyPack RegistryPolicyPack optional
      The registry policy pack metadata. May be null if the policy pack is unavailable.
    • ↳ id string required
      ID is the unique identifier for this policy pack in the registry. This is a UUID that corresponds to the policy pack’s database ID.
    • ↳ source string required
      Source indicates where this policy pack is hosted (e.g., “private”, “pulumi”). Currently, only “private” policy packs are supported.
    • ↳ publisher string required
      Publisher is the organization or user that published this policy pack. This corresponds to the Pulumi organization name.
    • ↳ name string required
      Name is the unique identifier for this policy pack within the publisher’s namespace. Policy pack names must be URL-safe and unique per publisher.
    • ↳ version string required
      Version is the semantic version of this policy pack. This represents the latest or specific version being referenced.
    • ↳ displayName string required
      DisplayName is a human-readable name for this policy pack. This is typically more descriptive than the technical name.
    • ↳ accessLevel enum required
      AccessLevel is the client’s level of access to this policy pack.
      Values:
      full — Full
      Full access to a policy pack (view + use)
      view-only — ViewOnly
      Access to view a policy pack
      deny — Deny
      No access to a policy pack
    • ↳ enforcementLevels array[string] required
      EnforcementLevels are the client’s allowed enforcement levels for this policy pack.
    Errors: 400 Invalid input 404 Organization or Policy Finding not found

    Get Policy Findings Compliance

    ▼
    POST /api/orgs/{orgName}/policy/findings/compliance

    Returns compliance data for policy Findings grouped by entity. The grouping can be by stack, cloud account, or severity, providing different views of the organization’s policy compliance posture. This powers the compliance dashboard in the Pulumi Cloud console.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: GetPolicyComplianceResultsRequest
    • entity enum required
      Entity type to filter by
      Values: stack, account, severity
    • continuationToken string optional
      Continuation token for pagination
    • size integer optional
      Number of results to return

    Responses

    200 OK
    Schema: GetPolicyComplianceResultsResponse
    • columns array[string] required
      Column names (policy pack names) in order
    • rows array[PolicyComplianceResult] required
      List of policy compliance result rows
    • ↳ entityName string required
      Entity name (stack name or account name)
    • ↳ scores array[integer] required
      Array of compliance scores correlating to columns array. -1 indicates N/A
    • continuationToken string optional
      Continuation token for next page
    Errors: 400 Invalid entity parameter. Must be 'stack', 'account', or 'severity' 404 Organization not found

    Export Policy Findings

    ▼
    POST /api/orgs/{orgName}/policy/findings/export

    Exports the policy Findings for an organization to CSV for offline analysis or reporting. A Finding is one resource failing one policy, tracked with a triage state; it keeps the same id when it recurs or when the policy pack version changes. The export includes the failing resource, policy name, enforcement level, and severity of each Finding.

    Request Parameters

    • orgName string path required
      The organization name
    • closed boolean query optional
      If true, return closed Findings; if false or omitted, return active Findings

    Request Body

    Schema: AngularGridGetRowsRequest

    Responses

    200 OK
    Errors: 400 Invalid request parameters 404 Organization not found

    Get Policy Findings Filters

    ▼
    POST /api/orgs/{orgName}/policy/findings/filters

    Returns the available filter options for listing policy Findings, such as policy pack names, enforcement levels, severity values, and resource types. Use it to populate filter controls for the Findings list.

    Request Parameters

    • orgName string path required
      The organization name
    • closed boolean query optional
      If true, return filters for closed Findings; if false or omitted, return filters for active Findings

    Request Body

    Schema: PolicyIssueFiltersRequest
    • filterModel AngularGridAdvancedFilterModel optional
      Optional filter model to apply when getting available filter values. Same format as used in policy issues list.
    • field string required
      Field name

    Responses

    200 OK
    Schema: PolicyIssueFiltersResponse
    • field string required
      The field name for which filter values are provided.
    • values array[PolicyIssueFilterValue] required
      The available filter values for the field.
    • ↳ name string required
      The name of the filter value.
    • ↳ count integer required
      The count of policy issues matching this filter value.
    Errors: 400 Field parameter is required 404 Organization not found

    Get Policy Findings Metadata

    ▼
    GET /api/orgs/{orgName}/policy/findings/metadata

    Returns high-level policy compliance counts for an organization: the number of enabled policies, the number of policies with open Findings, the number of resources with open Findings, and the number of resources governed by a policy group.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: PolicyResultsMetadata
    • policyTotalCount integer required
      Total number of policies
    • policyWithIssuesCount integer required
      Number of policies with issues
    • resourcesTotalCount integer required
      Total number of resources covered by policies
    • resourcesWithIssuesCount integer required
      Number of resources with issues
    Errors: 404 Organization not found

    List Policy Findings Policies

    ▼
    POST /api/orgs/{orgName}/policy/findings/policies

    Returns policy compliance data grouped by policy pack and policy name, showing how many stacks are in compliance or have open Findings for each individual policy rule. Supports pagination and filtering via the grid request format.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: AngularGridGetRowsRequest

    Responses

    200 OK
    Schema: ListPoliciesComplianceResponse
    • policies array[PolicyComplianceRow] required
      The list of policy compliance rows
    • ↳ policyName string required
      The name of the policy
    • ↳ severity enum required
      The severity level of the policy
      Values:
      — Unspecified
      low — Low
      medium — Medium
      high — High
      critical — Critical
    • ↳ failingResources integer required
      Number of resources failing this policy
    • ↳ governedResources integer required
      Total number of resources governed by this policy
    • ↳ percentCompliant integer required
      Percentage of resources that are compliant (0-100)
    • ↳ policyPack string required
      The policy pack this policy belongs to
    • ↳ policyGroupName string required
      The policy group this policy belongs to
    • ↳ policyGroupType enum required
      The type of the policy group this policy belongs to
      Values: audit, preventative
    • totalCount integer optional
      The total number of policies
    • continuationToken string optional
      Continuation token for pagination
    Errors: 400 Invalid grid request parameters 404 Organization not found

      The infrastructure as code platform for any cloud.

      Contact us Get started