Terraform policy evaluations API reference

Terraform policy evaluations evaluate policy sets during workspace runs. Each evaluation belongs to a run and an Init (Setup), Plan, or Apply stage. Use these endpoints to list evaluations, inspect policy set outcomes, and override eligible failures.

These endpoints are separate from the policy evaluations API for Sentinel and OPA, which associates evaluations with task stages.

All endpoint paths are relative to https://tfe.example.com/api/v2. In the sample requests, replace tfe.example.com with your Terraform Enterprise hostname.

Evaluation attributes

Evaluation resources have the JSON API type tf-policy-evaluations.

The run relationship identifies the parent run. The tf-policy-set-outcomes relationship links to the evaluation's policy set outcomes.

Evaluation statuses

The evaluation status is separate from the parent run state.

List Terraform policy evaluations for a run

GET /runs/:run_id/tf-policy-evaluations

This endpoint lists the Terraform policy evaluations associated with a run.

The endpoint returns the following responses.

Query parameters

This endpoint supports pagination.

Sample request

The following request lists evaluations for a run.

curl \
  --header "Authorization: Bearer TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/runs/run-CZcmD7eagjhyX0vN/tf-policy-evaluations

Sample response

The following response contains a plan-stage evaluation that passed.

{
  "data": [
    {
      "id": "tfpeval-8Jj9Hfoz892D9WMX",
      "type": "tf-policy-evaluations",
      "attributes": {
        "status": "passed",
        "stage-type": "Plan",
        "status-timestamps": {
          "queued-at": "2026-09-01T10:00:00Z",
          "running-at": "2026-09-01T10:00:05Z",
          "passed-at": "2026-09-01T10:00:10Z"
        },
        "created-at": "2026-09-01T09:59:00Z",
        "updated-at": "2026-09-01T10:00:10Z",
        "result-count": {
          "advisory-failed": 0,
          "mandatory-failed": 0,
          "mandatory-overridable-failed": 0,
          "passed": 1,
          "errored": 0,
          "unknown": 0
        },
        "error": null,
        "archivist-supported": true,
        "permissions": {
          "can-override": false
        },
        "actions": {
          "is-overridable": false
        }
      },
      "relationships": {
        "run": {
          "data": {
            "id": "run-CZcmD7eagjhyX0vN",
            "type": "runs"
          }
        },
        "tf-policy-set-outcomes": {
          "links": {
            "related": "/api/v2/tf-policy-evaluations/tfpeval-8Jj9Hfoz892D9WMX/tf-policy-set-outcomes"
          }
        }
      },
      "links": {
        "self": "/api/v2/tf-policy-evaluations/tfpeval-8Jj9Hfoz892D9WMX"
      }
    }
  ],
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a Terraform policy evaluation

GET /tf-policy-evaluations/:id

This endpoint returns details about a specific evaluation.

The endpoint returns the following responses.

Query parameters

Use the include parameter to request related resources.

Sample request

The following request retrieves an evaluation.

curl \
  --header "Authorization: Bearer TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/tf-policy-evaluations/tfpeval-8Jj9Hfoz892D9WMX

Sample response

The following response excerpt shows a plan-stage evaluation that passed and cannot be overridden. The full resource also contains the evaluation attributes and relationships.

{
  "data": {
    "id": "tfpeval-8Jj9Hfoz892D9WMX",
    "type": "tf-policy-evaluations",
    "attributes": {
      "status": "passed",
      "stage-type": "Plan",
      "archivist-supported": true,
      "permissions": {
        "can-override": false
      },
      "actions": {
        "is-overridable": false
      }
    }
  }
}

Override a Terraform policy evaluation

POST /tf-policy-evaluations/:id/actions/override

This endpoint overrides an eligible evaluation so the run can continue. The following requirements apply:

• Evaluation status: The evaluation must have the awaiting_override status.
• Policy enforcement: You can override failures for policies with the mandatory_overridable enforcement level. You cannot override an evaluation if any policy with the mandatory enforcement level failed. Refer to Terraform policy enforcement levels for more information.

Only plan-stage evaluations for runs that are not plan-only support overrides. When the associated run is paused in tf_policy_override, overriding the evaluation allows the run to continue.

You need manage policy overrides permissions to override failed Terraform policy evaluations. Check permissions.can-override and actions.is-overridable before submitting an override.

The endpoint returns the following responses.

Request body

The request body is optional. Supply the comment as a top-level property, not inside a JSON API data object.

Sample request

The following request overrides an evaluation and records a comment.

curl \
  --header "Authorization: Bearer TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data '{"comment":"Approved exception for this run."}' \
  https://tfe.example.com/api/v2/tf-policy-evaluations/tfpeval-8Jj9Hfoz892D9WMX/actions/override

Sample response

The following response excerpt shows the updated evaluation. Overriding an evaluation does not change its failed policy result counts.

{
  "data": {
    "id": "tfpeval-8Jj9Hfoz892D9WMX",
    "type": "tf-policy-evaluations",
    "attributes": {
      "status": "overridden",
      "stage-type": "Plan",
      "status-timestamps": {
        "awaiting-override-at": "2026-09-01T10:00:10Z",
        "overridden-at": "2026-09-01T10:05:00Z"
      },
      "permissions": {
        "can-override": false
      },
      "actions": {
        "is-overridable": false
      }
    }
  }
}

List Terraform policy set outcomes

GET /tf-policy-evaluations/:tf_policy_evaluation_id/tf-policy-set-outcomes

This endpoint lists policy set outcomes for an evaluation.

The endpoint returns the following responses.

Query parameters

This endpoint supports pagination and outcome filters. Percent-encode [ as %5B and ] as %5D if your tooling does not encode them.

Each numeric index defines a group. Conditions in the same group use AND; different groups use OR. Filters select policy sets containing matching policy outcomes. They do not remove individual policy results from a matching policy set.

Use enforcement_level for these endpoints, not the enforcementLevel parameter used by the Sentinel and OPA policy evaluations API.

Sample request

The following request returns policy set outcomes containing an errored policy or a failed policy with mandatory_overridable enforcement. The --globoff option prevents curl from interpreting square brackets as URL patterns.

curl --globoff \
  --header "Authorization: Bearer TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  "https://tfe.example.com/api/v2/tf-policy-evaluations/tfpeval-8Jj9Hfoz892D9WMX/tf-policy-set-outcomes?filter[0][status]=errored&filter[1][status]=failed&filter[1][enforcement_level]=mandatory_overridable"

Sample response

The following response contains a policy set with one overridable failure. The download URL is illustrative; use the URL returned by your Terraform Enterprise instance.

{
  "data": [
    {
      "id": "tfpsout-cu8E9a97LBepZZXd",
      "type": "tf-policy-set-outcomes",
      "attributes": {
        "outcomes": null,
        "error": null,
        "overridable": false,
        "policy-set-name": "workspace-resource-policies",
        "policy-set-description": "Resource policies for workspace runs.",
        "result-count": {
          "advisory-failed": 0,
          "mandatory-failed": 0,
          "mandatory-overridable-failed": 1,
          "passed": 0,
          "errored": 0,
          "unknown": 0
        },
        "policy-set-result-url": "https://archivist.terraform.io/v1/object/..."
      },
      "relationships": {
        "tf-policy-evaluation": {
          "data": {
            "id": "tfpeval-8Jj9Hfoz892D9WMX",
            "type": "tf-policy-evaluations"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a Terraform policy set outcome

GET /tf-policy-set-outcomes/:id

This endpoint returns a specific policy set outcome.

The endpoint returns the following responses.

Sample request

The following request retrieves a policy set outcome.

curl \
  --header "Authorization: Bearer TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/tf-policy-set-outcomes/tfpsout-cu8E9a97LBepZZXd

Sample response

The following response excerpt shows the outcome's result counts and download URL. The endpoint returns the same resource attributes as the list endpoint, with a single object in data instead of an array.

The download URL is illustrative; use the URL returned by your Terraform Enterprise instance.

{
  "data": {
    "id": "tfpsout-cu8E9a97LBepZZXd",
    "type": "tf-policy-set-outcomes",
    "attributes": {
      "policy-set-name": "workspace-resource-policies",
      "policy-set-description": "Resource policies for workspace runs.",
      "result-count": {
        "advisory-failed": 0,
        "mandatory-failed": 0,
        "mandatory-overridable-failed": 1,
        "passed": 0,
        "errored": 0,
        "unknown": 0
      },
      "policy-set-result-url": "https://archivist.terraform.io/v1/object/..."
    }
  }
}

Retrieve full policy results

Policy set outcome resources have the JSON API type tf-policy-set-outcomes. The result-count attribute summarizes policy results, while full results contain policy diagnostics and resource details.

To retrieve full results:

1. Retrieve the policy set outcome.
2. Download the full policy results from its policy-set-result-url.

Download URLs expire after 30 minutes. Retrieve the outcome again to obtain a fresh URL.

If policy-set-result-url is null, no result download is available. Check the parent evaluation's status and error attributes rather than interpreting a missing URL as a successful evaluation.

Downloaded policy results

The downloaded content is a JSON array of policy outcomes for one policy set. Each entry describes a policy's enforcement level, result, diagnostics, and resources. Field names use underscores, such as policy_name and enforcement_level.

Each array entry contains the following fields.

Diagnostic entries can include code, context, start_line, and summary to identify the policy code and explain the result. When there are no resource diagnostics, the error message appears directly on the diagnostic entry as error_message, and the resources array is omitted. Otherwise, the resources array contains resource-specific details:

Resource diagnostic fields are omitted when they have no value. Entries in passed_resources contain a resource_name and, when present, an info_messages array.

The download does not include aggregate counts. Use the policy set outcome API resource's result-count for totals. These totals count policies, not resources: a failed policy can contain both resource diagnostics and resources that passed.

Sample downloaded content

The following example contains one failed policy with mandatory_overridable enforcement. One resource failed the policy, while another passed.

[
  {
    "policy_name": "resource_policy.aws_s3_bucket.approved_bucket_name",
    "enforcement_level": "mandatory_overridable",
    "status": "failed",
    "file_name": "resource-policies.policy.hcl",
    "diagnostics": [
      {
        "context": "resource_policy \"aws_s3_bucket\" \"approved_bucket_name\"",
        "start_line": 5,
        "summary": "Bucket names must start with approved-.",
        "resources": [
          {
            "resource_name": "aws_s3_bucket.example",
            "error_message": "The bucket name does not use the required prefix.",
            "file_name": "main.tf",
            "start_line": 1,
            "values": [
              {
                "traversal": "attrs.bucket",
                "statement": "is \"unapproved-bucket\""
              }
            ]
          }
        ]
      }
    ],
    "passed_resources": [
      {
        "resource_name": "aws_s3_bucket.compliant",
        "info_messages": [
          "The bucket name uses the required prefix."
        ]
      }
    ]
  }
]