Applies API reference
An apply represents the results of applying a Terraform Run's execution plan.
Attributes
Apply States
You'll find the apply state indata.attributes.status, as one of the following values.
| State | Description |
|---|---|
pending | The initial status of a apply once it has been created. |
managed_queued/queued | The apply has been queued, awaiting backend service capacity to run terraform. |
running | The apply is running. |
errored | The apply has errored. This is a final state. |
canceled | The apply has been canceled. This is a final state. |
finished | The apply has completed successfully. This is a final state. |
unreachable | The apply will not run. This is a final state. |
Show an apply
GET /applies/:id
| Parameter | Description |
|---|---|
id | The ID of the apply to show. |
There is no endpoint to list applies. You can find the ID for an apply in therelationships.apply property of a run object.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "applies") | The request was successful |
| 404 | JSON API error object | Apply 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/applies/apply-47MBvjwzBG8YKc2vSample Response
{ "data": { "id": "apply-47MBvjwzBG8YKc2v", "type": "applies", "attributes": { "execution-details": { "mode": "remote", }, "status": "finished", "status-timestamps": { "queued-at": "2018-10-17T18:58:27+00:00", "started-at": "2018-10-17T18:58:29+00:00", "finished-at": "2018-10-17T18:58:37+00:00" }, "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg", "resource-additions": 1, "resource-changes": 0, "resource-destructions": 0, "resource-imports": 0 }, "relationships": { "state-versions": { "data": [ { "id": "sv-TpnsuD3iewwsfeRD", "type": "state-versions" }, { "id": "sv-Fu1n6a3TgJ1Typq9", "type": "state-versions" } ] } }, "links": { "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v" } }}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 apply response will include additional details about the agent pool and agent used.
{ "data": { "id": "apply-47MBvjwzBG8YKc2v", "type": "applies", "attributes": { "execution-details": { "agent-id": "agent-S1Y7tcKxXPJDQAvq", "agent-name": "agent_01", "agent-pool-id": "apool-Zigq2VGreKq7nwph", "agent-pool-name": "first-pool", "mode": "agent", }, "status": "finished", "status-timestamps": { "queued-at": "2018-10-17T18:58:27+00:00", "started-at": "2018-10-17T18:58:29+00:00", "finished-at": "2018-10-17T18:58:37+00:00" }, "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg", "resource-additions": 1, "resource-changes": 0, "resource-destructions": 0, "resource-imports": 0 }, "relationships": { "state-versions": { "data": [ { "id": "sv-TpnsuD3iewwsfeRD", "type": "state-versions" }, { "id": "sv-Fu1n6a3TgJ1Typq9", "type": "state-versions" } ] } }, "links": { "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v" } }}Recover a failed state upload after applying
GET /applies/:id/errored-state
| Parameter | Description |
|---|---|
id | The ID of the apply to recover state for. |
It is possible that during the course of a Run, Terraform may fail to upload astate file. This can happen for a variety of reasons, but should be anexceptionally rare occurrence. HCP Terraform agent versions greater than 1.12.0include a fallback mechanism which attempts to upload the state directly toHCP Terraform's backend storage system in these cases. This endpoint thenmakes the raw data from these failed uploads available to users who areauthorized to read the state contents.
| Status | Response | Reason |
|---|---|---|
| 307 | HTTP temporary redirect to state storage URL | Errored state available and user is authorized to read it |
| 404 | JSON API error object | Apply not found, errored state not uploaded, or user unauthorized to perform action |
When a 307 redirect is returned, the storage URL to the raw state file will bepresent in theLocation header of the response. The URL in theLocationheader will expire after one minute. It is recommended for the API client tofollow the redirect immediately. Each successful request to the errored-stateendpoint will generate a new, unique storage URL with the same one minuteexpiration window.
Sample Request
curl \ --header "Authorization: Bearer $TOKEN" \ https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v/errored-stateSample Response
HTTP/1.1 307 Temporary RedirectContent-Length: 22Content-Type: text/plainLocation: https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg 307 Temporary Redirect