Stack policy evaluations API reference

Terraform policy evaluations run as part of a Stacks plan. When Terraform Enterprise executes a Stack plan step and the organization is entitled to policy enforcement, Terraform Enterprise creates a Terraform policy evaluation and one policy set outcome per attached policy set, all within the same job that runs the plan.

This set of APIs provides endpoints to show a Terraform policy evaluation and list its associated policy set outcomes

Show a Stack policy evaluation

GET /stack-policy-evaluations/:stack_policy_evaluation_id

Parameter	Description
`:stack_policy_evaluation_id`	The external ID of the policy evaluation to retrieve.

Status	Response	Reason
200	JSON API document	Success
401	JSON API error object	User is not authorized to read this policy evaluation
404	JSON API error object	Policy evaluation not found

Query Parameters

Parameter	Description
`include`	Optional. Comma-separated list of related resources to sideload. Supported value: `stack_policy_set_outcomes`.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh

Sample Response

{
  "data": {
    "id": "speval-HjkrEHMbYQrwJQHh",
    "type": "stack-policy-evaluations",
    "attributes": {
      "status": "passed",
      "policy-attachable-id": "stoplan-qPRDmB9v9D36zpVN",
      "policy-attachable-type": "plan",
      "result-count": {
        "passed": 2,
        "errored": 0,
        "unknown": 0,
        "advisory-failed": 3,
        "mandatory-failed": 0,
        "mandatory-overridable-failed": 0
      },
      "error": null,
      "created-at": "2026-09-29T08:17:18.443Z",
      "updated-at": "2026-09-29T08:17:37.530Z"
    },
    "relationships": {
      "stack-policy-set-outcomes": {
        "links": {
          "related": "/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh/stack-policy-set-outcomes"
        }
      }
    },
    "links": {
      "self": "/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh",
      "stack-policy-set-outcomes": "/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh/stack-policy-set-outcomes"
    }
  }
}

Attribute reference

Attribute	Type	Description
`status`	string	Current evaluation status. One of `pending`, `passed`, `failed`, `errored`, or `unknown`.
`policy-attachable-id`	string	External ID of the Stack plan this evaluation is attached to.
`policy-attachable-type`	string	The type of resource the evaluation is attached to. Currently always `"plan"`.
`result-count`	object	Aggregate policy result counts. See result-count object below.
`error`	object \| null	Structured error details when the evaluation status is `errored`. See error object below. `null` when no error occurred.
`created-at`	string	ISO 8601 timestamp when the evaluation was created.
`updated-at`	string	ISO 8601 timestamp when the evaluation was last updated.

result-count object

Key	Type	Description
`advisory-failed`	integer	Number of advisory policies that failed.
`mandatory-failed`	integer	Number of hard mandatory policies that failed.
`mandatory-overridable-failed`	integer	Number of overridable mandatory policies that failed.
`passed`	integer	Total number of policies that passed.
`errored`	integer	Number of policies that encountered an error during evaluation.
`unknown`	integer	Number of policies whose result could not be determined.

error object

Terraform Enterprise sets the error attribute when the evaluation status is errored and the failure is the result of a compatibility or configuration problem detected before the agent could run policies. It is null in all other cases.

Key	Type	Description
`type`	string	Machine-readable error category. Possible values are `incompatible_agent_version`, `incompatible_terraform_version_error`, `tool_version_error`, `missing_stack_configuration`.
`summary`	string	Short human-readable summary of the error.
`detail`	string	Detailed description of the error and how to resolve it.

List stack policy set outcomes

GET /stack-policy-evaluations/:stack_policy_evaluation_id/stack-policy-set-outcomes

Parameter	Description
`:stack_policy_evaluation_id`	The external ID of the policy evaluation to list outcomes for.

This endpoint lists all policy set outcomes associated with the given Stack policy evaluation. Each outcome corresponds to a single policy set that was evaluated.

Status	Response	Reason
200	JSON API document	Success
401	JSON API error object	User is not authorized
404	JSON API error object	Policy evaluation not found

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling does not automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 outcomes per page.
`filter[n][status]`	Optional. Filters outcomes by policy result status. Must be one of `passed`, `failed`, or `errored`. Can be combined with `filter[n][enforcement_level]`.
`filter[n][enforcement_level]`	Optional. Filters outcomes by policy enforcement level. Must be one of `advisory`, `mandatory`, or `mandatory_overridable`. Only meaningful alongside a non-errored `status` filter.

You can use indexed filter[n] parameters to combine multiple status and enforcement-level combinations. The endpoint returns all policy set outcomes that contain at least one individual policy result matching any of the specified filter criteria.

Sample Requests

The following sample requests demonstrate common use cases.

All policy set outcomes

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh/stack-policy-set-outcomes

Filter by failed mandatory and errored outcomes

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  "https://tfe.example.com/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh/stack-policy-set-outcomes?filter[0][status]=failed&filter[0][enforcement_level]=mandatory&filter[1][status]=errored"

Sample Response

{
  "data": [
    {
      "id": "spsout-UK7m5PXEFd2rrk9Z",
      "type": "stack-policy-set-outcomes",
      "attributes": {
        "policy-set-name": "test-tf-policies",
        "policy-set-description": "Terraform policies for stacks",
        "result-count": {
          "advisory_failed": 1,
          "mandatory_failed": 0,
          "mandatory_overridable_failed": 0,
          "passed": 2,
          "errored": 0,
          "unknown": 0
        },
        "policy-set-result-url": "https://archivist.terraform.io/v1/object"
      },
      "relationships": {
        "stack-policy-evaluation": {
          "data": {
            "id": "speval-HjkrEHMbYQrwJQHh",
            "type": "stack-policy-evaluations"
          }
        }
      }
    }
  ],
  "links": {
    "self": "/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh/stack-policy-set-outcomes?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh/stack-policy-set-outcomes?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "/api/v2/stack-policy-evaluations/speval-HjkrEHMbYQrwJQHh/stack-policy-set-outcomes?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Attribute reference

Attribute	Type	Description
`policy-set-name`	string	The name of the policy set evaluated.
`policy-set-description`	string \| null	The description of the policy set, or `null` if no description was set.
`result-count`	object	Per-enforcement-level policy result counts for this policy set. See result-count object.
`policy-set-result-url`	string	A pre-signed URL where you can download the raw JSON result file produced by the agent for this policy set. The URL is active for 30 minutes.