HashiCorp Developer AI Private beta now available Sign up today
Terraform
Terraform Home

You are viewing documentation for version v202409-2. View latest version.

Applies API

An apply represents the results of applying a Terraform Run's execution plan.

Attributes

Apply States

You'll find the apply state in data.attributes.status, as one of the following values.

StateDescription
pendingThe initial status of a apply once it has been created.
managed_queued/queuedThe apply has been queued, awaiting backend service capacity to run terraform.
runningThe apply is running.
erroredThe apply has errored. This is a final state.
canceledThe apply has been canceled. This is a final state.
finishedThe apply has completed successfully. This is a final state.
unreachableThe apply will not run. This is a final state.

Show an apply

GET /applies/:id

ParameterDescription
idThe ID of the apply to show.

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

StatusResponseReason
200JSON API document (type: "applies")The request was successful
404JSON API error objectApply 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-47MBvjwzBG8YKc2v

Sample 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

ParameterDescription
idThe ID of the apply to recover state for.

It is possible that during the course of a Run, Terraform may fail to upload a state file. This can happen for a variety of reasons, but should be an exceptionally rare occurance. HCP Terraform agent versions greater than 1.12.0 include a fallback mechanism which attempts to upload the state directly to HCP Terraform's backend storage system in these cases. This endpoint then makes the raw data from these failed uploads available to users who are authorized to read the state contents.

StatusResponseReason
307HTTP temporary redirect to state storage URLErrored state available and user is authorized to read it
404JSON API error objectApply 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 be present in the Location header of the response. The URL in the Location header will expire after one minute. It is recommended for the API client to follow the redirect immediately. Each successful request to the errored-state endpoint will generate a new, unique storage URL with the same one minute expiration window.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v/errored-state

Sample Response

HTTP/1.1 307 Temporary Redirect
Content-Length: 22
Content-Type: text/plain
Location: https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg

307 Temporary Redirect