Plans API
A plan represents the execution plan of a Run in a Terraform workspace.
Attributes
Plan States
The plan state is found indata.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 therelationships.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-8F5JFydVYAmtTjETSample 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, "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, "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 theJSON 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 of1 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 withorganization tokens. You must access it with auser token orteam 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