Plans API reference

A plan represents the execution plan of a Run in a Terraform workspace.

Attributes

Plan States

The plan state is found in data.attributes.status, and you can reference the following list of possible states.

State	Description
`pending`	The initial status of a plan once it has been created.
`managed_queued`/`queued`	The plan has been queued, awaiting backend service capacity to run terraform.
`running`	The plan is running.
`errored`	The plan has errored. This is a final state.
`canceled`	The plan has been canceled. This is a final state.
`finished`	The plan has completed successfully. This is a final state.
`unreachable`	The plan will not run. This is a final state.

Show a plan

GET /plans/:id

Parameter	Description
`id`	The ID of the plan to show.

There is no endpoint to list plans. You can find the ID for a plan in the relationships.plan property of a run object.

Status	Response	Reason
200	JSON API document (`type: "plans"`)	The request was successful
404	JSON API error object	Plan not found, or user unauthorized to perform action

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/plans/plan-8F5JFydVYAmtTjET

Sample Response

{
  "data": {
    "id": "plan-8F5JFydVYAmtTjET",
    "type": "plans",
    "attributes": {
      "execution-details": {
        "mode": "remote",
      },
      "generated-configuration": false,
      "has-changes": true,
      "resource-additions": 0,
      "resource-changes": 1,
      "resource-destructions": 0,
      "resource-imports": 0,
      "action-invocations": 0,
      "status": "finished",
      "status-timestamps": {
        "queued-at": "2018-07-02T22:29:53+00:00",
        "pending-at": "2018-07-02T22:29:53+00:00",
        "started-at": "2018-07-02T22:29:54+00:00",
        "finished-at": "2018-07-02T22:29:58+00:00"
      },
      "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg"
    },
    "relationships": {
      "state-versions": {
        "data": []
      }
    },
    "links": {
      "self": "/api/v2/plans/plan-8F5JFydVYAmtTjET",
      "json-output": "/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output"
    }
  }
}

Using HCP Terraform agents

HCP Terraform agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. When a workspace is set to use the agent execution mode, the plan response will include additional details about the agent pool and agent used.

{
  "data": {
    "id": "plan-8F5JFydVYAmtTjET",
    "type": "plans",
    "attributes": {
      "execution-details": {
        "agent-id": "agent-S1Y7tcKxXPJDQAvq",
        "agent-name": "agent_01",
        "agent-pool-id": "apool-Zigq2VGreKq7nwph",
        "agent-pool-name": "first-pool",
        "mode": "agent",
      },
      "generated-configuration": false,
      "has-changes": true,
      "resource-additions": 0,
      "resource-changes": 1,
      "resource-destructions": 0,
      "resource-imports": 0,
      "action-invocations": 0,
      "status": "finished",
      "status-timestamps": {
        "queued-at": "2018-07-02T22:29:53+00:00",
        "pending-at": "2018-07-02T22:29:53+00:00",
        "started-at": "2018-07-02T22:29:54+00:00",
        "finished-at": "2018-07-02T22:29:58+00:00"
      },
      "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg"
    },
    "relationships": {
      "state-versions": {
        "data": []
      }
    },
    "links": {
      "self": "/api/v2/plans/plan-8F5JFydVYAmtTjET",
      "json-output": "/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output"
    }
  }
}

Retrieve the JSON execution plan

GET /plans/:id/json-output

GET /runs/:id/plan/json-output

These endpoints generate a temporary authenticated URL to the location of the JSON formatted execution plan. When successful, this endpoint responds with a temporary redirect that should be followed. If using a client that can follow redirects, you can use this endpoint to save the .json file locally without needing to save the temporary URL.

This temporary URL provided by the redirect has a life of 1 minute, and should not be relied upon beyond the initial request. If you need repeat access, you should use this endpoint to generate a new URL each time.

Note: This endpoint is available for plans using Terraform 0.12 and later. For Terraform Enterprise, this endpoint is available from v202005-1, and its stability was improved in v202007-1.

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token that has admin level access to the workspace. (More about permissions.)

Status	Response	Reason
204	No Content	Plan JSON supported, but plan has not yet completed.
307	Temporary Redirect	Plan JSON found and temporary download URL generated
422	JSON API error object	Plan does not use a supported version of terraform (< 0.12.X)

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --location \
  https://app.terraform.io/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output |
  > json-output.json

Soft delete plan backing data

POST /plans/:id/actions/soft-delete-backing-data

This endpoint directs Terraform Enterprise to soft delete the backing files associated with the plan. Soft deletion marks the plan for garbage collection. Terraform permanently deletes plans marked for soft deletion after a set number of days unless the plan is restored. Once a plan is soft deleted, any attempts to read the plan's backing data fail.

This endpoint can only soft delete plans that meet the following criteria:

The associated run is in a terminal state.
The associated run is not the current run in the workspace.

Otherwise, the endpoint returns a 409 Conflict.

Status	Response	Reason(s)
204	No Content	Terraform successfully marked the plan's backing data for garbage collection.
404	JSON API error object	Plan not found, or user is not authorized to perform this action.
409	JSON API error object	The plan does not meet the eligibility criteria for soft deletion.

Request body

No request body.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://<TFE_HOSTNAME>/api/v2/plans/plan-8F5JFydVYAmtTjET/actions/soft-delete-backing-data

Restore plan backing data

POST /plans/:id/actions/restore-backing-data

This endpoint directs Terraform Enterprise to restore the backing files associated with a plan that has been marked for garbage collection. This endpoint can only restore plans that are not in a backing_data_permanently_deleted state. Otherwise, the endpoint returns an error.

Status	Response	Reason(s)
204	No Content	Terraform successfully initiated the restore process.
404	JSON API error object	Plan not found, or user is not authorized to perform this action.

Request body

No request body.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://<TFE_HOSTNAME>/api/v2/plans/plan-8F5JFydVYAmtTjET/actions/restore-backing-data

Permanently delete plan backing data

POST /plans/:id/actions/permanently-delete-backing-data

This endpoint directs Terraform Enterprise to immediately and permanently delete the files associated with a plan that have been marked for garbage collection. This endpoint can only permanently delete plans that are in a backing_data_soft_deleted state. Otherwise, the endpoint returns a 409 Conflict.

Status	Response	Reason(s)
204	No Content	Terraform successfully permanently deleted the plan's backing data.
404	JSON API error object	Plan not found, or user is not authorized to perform this action.
409	JSON API error object	The plan is not in a `backing_data_soft_deleted` state.

Request body

No request body.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://<TFE_HOSTNAME>/api/v2/plans/plan-8F5JFydVYAmtTjET/actions/permanently-delete-backing-data