• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform Cloud and Enterprise

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
      • Run Tasks
      • Stages and Results
      • Custom Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
      • Overview
      • Module Sharing
      • Organizations
      • Runs
      • Settings
      • Terraform Versions
      • Users
      • Workspaces
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Drift Detection
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Terraform Enterprise Admin

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Runs API

Note: Before working with the runs or configuration versions APIs, read the API-driven run workflow page, which includes both a full overview of this workflow and a walkthrough of a simple implementation of it.

Performing a run on a new configuration is a multi-step process.

  1. Create a configuration version on the workspace.
  2. Upload configuration files to the configuration version.
  3. Create a run on the workspace; this is done automatically when a configuration file is uploaded.
  4. Create and queue an apply on the run; if the run can't be auto-applied.

Alternatively, you can create a run with a pre-existing configuration version, even one from another workspace. This is useful for promoting known good code from one workspace to another.

»Attributes

»Run States

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

StateDescription
pendingThe initial status of a run once it has been created.
fetchingThe run is waiting for Terraform Cloud to fetch the configuration from VCS.
plan_queuedOnce a workspace has the availability to start a new run, the next run will transition to plan_queued. This status indicates that the it should start as soon as the backend services that run terraform have available capacity. In Terraform Cloud, you should seldom see this status, as our aim is to always have capacity. However, in Terraform Enterprise this status will be more common due to the self-hosted nature.
planningThe planning phase of a run is in progress.
plannedThe planning phase of a run has completed.
cost_estimatingThe cost estimation phase of a run is in progress.
cost_estimatedThe cost estimation phase of a run has completed.
policy_checkingThe sentinel policy checking phase of a run is in progress.
policy_overrideA sentinel policy has soft failed, and can be overridden.
policy_soft_failedA sentinel policy has soft failed for a plan-only run. This is a final state.
policy_checkedThe sentinel policy checking phase of a run has completed.
confirmedThe plan produced by the run has been confirmed.
post_plan_runningThe post-plan phase of the run is in progress.
post_plan_completedThe post-plan phase of the run has completed.
planned_and_finishedThe completion of a run containing a plan only, or a run that produces a plan with no changes to apply. This is a final state.
apply_queuedOnce the changes in the plan have been confirmed, the run run will transition to apply_queued. This status indicates that the run should start as soon as the backend services that run terraform have available capacity. In Terraform Cloud, you should seldom see this status, as our aim is to always have capacity. However, in Terraform Enterprise this status will be more common due to the self-hosted nature.
applyingThe applying phase of a run is in progress.
appliedThe applying phase of a run has completed.
discardedThe run has been discarded. This is a final state.
erroredThe run has errored. This is a final state.
canceledThe run has been canceled.
force_canceledA workspace admin forcefully canceled the run.

»Create a Run

POST /runs

A run performs a plan and apply, using a configuration version and the workspace’s current variables. You can specify a configuration version when creating a run; if you don’t provide one, the run defaults to the workspace’s most recently used version. (A configuration version is “used” when it is created or used for a run in this workspace.)

Creating a run requires permission to queue plans for the specified workspace. (More about permissions.)

When creating a run, you may optionally provide a list of variable objects containing key and value attributes. These values apply to that run specifically and take precedence over variables with the same key applied to the workspace(e.g., variable sets). Refer to Variable Precedence for more information. All values must be expressed as an HCL literal in the same syntax you would use when writing Terraform code. Refer to Types in the Terraform documentation for more details.

Sample Run Variables:

"attributes": {
  "variables": [
    { "key": "replicas", "value": "2" },
    { "key": "access_key", "value": "\"ABCDE12345\"" }
  ]
}
"attributes": {
  "variables": [
    { "key": "replicas", "value": "2" },
    { "key": "access_key", "value": "\"ABCDE12345\"" }
  ]
}

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

»Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.attributes.auto-applyboolThe current Auto Apply setting in the workspaceWhether to automatically apply changes when a Terraform plan is successful. Defaults to the Auto Apply workspace setting.
data.attributes.is-destroyboolfalseSpecifies whether this plan is a destroy plan that will destroy all provisioned resources. Mutually exclusive with refresh-only.
data.attributes.messagestring"Queued manually via the Terraform Enterprise API"Specifies the message associated with this run.
data.attributes.refreshbooltrueSpecifies whether or not to refresh the state before a plan.
data.attributes.refresh-onlyboolfalseWhether this run should refresh the state without modifying any resources. Mutually exclusive with is-destroy.
data.attributes.replace-addrsarray[string]Specifies an optional list of resource addresses to be passed to the -replace flag.
data.attributes.target-addrsarray[string]Specifies an optional list of resource addresses to be passed to the -target flag.
data.attributes.variablesarray[{key, value}](empty array)Specifies an optional list of run-specific variable values. Refer to Run-Specific Variables for details.
data.attributes.plan-onlybool(from configuration version)Specifies if this is a speculative, plan-only run that Terraform cannot apply. Often used in conjunction with terraform-version in order to test whether an upgrade would succeed.
data.attributes.terraform-versionstringSpecifies the Terraform version to use in this run. Only valid for plan-only runs; must be a valid Terraform version available to the organization.
data.attributes.allow-empty-applyboolSpecifies whether Terraform can apply the run even when the plan contains no changes. Often used to upgrade state after upgrading a workspace to a new terraform version.
data.relationships.workspace.data.idstringSpecifies the workspace ID where the run will be executed.
data.relationships.configuration-version.data.idstringSpecifies the configuration version to use for this run. If the configuration-version object is omitted, the run will be created using the workspace's latest configuration version.
StatusResponseReason
201JSON API document (type: "runs")Successfully created a run
404JSON API error objectOrganization or workspace not found, or user unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)

»Sample Payload

{
  "data": {
    "attributes": {
      "message": "Custom message"
    },
    "type":"runs",
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "ws-LLGHCr4SWy28wyGN"
        }
      },
      "configuration-version": {
        "data": {
          "type": "configuration-versions",
          "id": "cv-n4XQPBa2QnecZJ4G"
        }
      }
    }
  }
}
{
  "data": {
    "attributes": {
      "message": "Custom message"
    },
    "type":"runs",
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "ws-LLGHCr4SWy28wyGN"
        }
      },
      "configuration-version": {
        "data": {
          "type": "configuration-versions",
          "id": "cv-n4XQPBa2QnecZJ4G"
        }
      }
    }
  }
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs

»Sample Response

{
  "data": {
    "id": "run-CZcmD7eagjhyX0vN",
    "type": "runs",
    "attributes": {
      "actions": {
        "is-cancelable": true,
        "is-confirmable": false,
        "is-discardable": false,
        "is-force-cancelable": false
      },
      "canceled-at": null,
      "created-at": "2021-05-24T07:38:04.171Z",
      "has-changes": false,
      "auto-apply": false,
      "allow-empty-apply": false,
      "is-destroy": false,
      "message": "Custom message",
      "plan-only": false,
      "source": "tfe-api",
      "status-timestamps": {
        "plan-queueable-at": "2021-05-24T07:38:04+00:00"
      },
      "status": "pending",
      "trigger-reason": "manual",
      "target-addrs": null,
      "permissions": {
        "can-apply": true,
        "can-cancel": true,
        "can-comment": true,
        "can-discard": true,
        "can-force-execute": true,
        "can-force-cancel": true,
        "can-override-policy-check": true
      },
      "refresh": false,
      "refresh-only": false,
      "replace-addrs": null,
      "variables": []
    },
    "relationships": {
      "apply": {...},
      "comments": {...},
      "configuration-version": {...},
      "cost-estimate": {...},
      "created-by": {...},
      "input-state-version": {...},
      "plan": {...},
      "run-events": {...},
      "policy-checks": {...},
      "workspace": {...},
      "workspace-run-alerts": {...}
      }
    },
    "links": {
      "self": "/api/v2/runs/run-CZcmD7eagjhyX0vN"
    }
  }
}
{
  "data": {
    "id": "run-CZcmD7eagjhyX0vN",
    "type": "runs",
    "attributes": {
      "actions": {
        "is-cancelable": true,
        "is-confirmable": false,
        "is-discardable": false,
        "is-force-cancelable": false
      },
      "canceled-at": null,
      "created-at": "2021-05-24T07:38:04.171Z",
      "has-changes": false,
      "auto-apply": false,
      "allow-empty-apply": false,
      "is-destroy": false,
      "message": "Custom message",
      "plan-only": false,
      "source": "tfe-api",
      "status-timestamps": {
        "plan-queueable-at": "2021-05-24T07:38:04+00:00"
      },
      "status": "pending",
      "trigger-reason": "manual",
      "target-addrs": null,
      "permissions": {
        "can-apply": true,
        "can-cancel": true,
        "can-comment": true,
        "can-discard": true,
        "can-force-execute": true,
        "can-force-cancel": true,
        "can-override-policy-check": true
      },
      "refresh": false,
      "refresh-only": false,
      "replace-addrs": null,
      "variables": []
    },
    "relationships": {
      "apply": {...},
      "comments": {...},
      "configuration-version": {...},
      "cost-estimate": {...},
      "created-by": {...},
      "input-state-version": {...},
      "plan": {...},
      "run-events": {...},
      "policy-checks": {...},
      "workspace": {...},
      "workspace-run-alerts": {...}
      }
    },
    "links": {
      "self": "/api/v2/runs/run-CZcmD7eagjhyX0vN"
    }
  }
}

»Apply a Run

POST /runs/:run_id/actions/apply

ParameterDescription
run_idThe run ID to apply

Applies a run that is paused waiting for confirmation after a plan. This includes runs in the "needs confirmation" and "policy checked" states. This action is only required for runs that can't be auto-applied. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs for the workspace.

Note: If the run has a soft failed sentinel policy, you will need to override the policy check before Terraform can apply the run. You can find policy check details in the relationships section of the run details endpoint response.

Applying a run requires permission to apply runs for the workspace. (More about permissions.)

This endpoint queues the request to perform an apply; the apply might not happen immediately.

Since this endpoint represents an action (not a resource), it does not return any object in the response body.

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

StatusResponseReason(s)
202noneSuccessfully queued an apply request.
409JSON API error objectRun was not paused for confirmation; apply not allowed.

»Request Body

This POST endpoint allows an optional JSON object with the following properties as a request payload.

Key pathTypeDefaultDescription
commentstringnullAn optional comment about the run.

»Sample Payload

This payload is optional, so the curl command will work without the --data @payload.json option too.

{
  "comment":"Looks good to me"
}
{
  "comment":"Looks good to me"
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/apply
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/apply

»List Runs in a Workspace

GET /workspaces/:workspace_id/runs

ParameterDescription
workspace_idThe workspace ID to list runs for.
StatusResponseReason
200Array of JSON API documents (type: "runs")Successfully listed runs

»Query Parameters

This endpoint supports pagination with standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

ParameterDescription
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 runs per page.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs

»Sample Response

{
  "data": [
    {
      "id": "run-CZcmD7eagjhyX0vN",
      "type": "runs",
      "attributes": {
        "actions": {
          "is-cancelable": true,
          "is-confirmable": false,
          "is-discardable": false,
          "is-force-cancelable": false
        },
        "canceled-at": null,
        "created-at": "2021-05-24T07:38:04.171Z",
        "has-changes": false,
        "auto-apply": false,
        "allow-empty-apply": false,
        "is-destroy": false,
        "message": "Custom message",
        "plan-only": false,
        "source": "tfe-api",
        "status-timestamps": {
          "plan-queueable-at": "2021-05-24T07:38:04+00:00"
        },
        "status": "pending",
        "trigger-reason": "manual",
        "target-addrs": null,
        "permissions": {
          "can-apply": true,
          "can-cancel": true,
          "can-comment": true,
          "can-discard": true,
          "can-force-execute": true,
          "can-force-cancel": true,
          "can-override-policy-check": true
        },
        "refresh": false,
        "refresh-only": false,
        "replace-addrs": null,
        "variables": []
      },
      "relationships": {
        "apply": {...},
        "comments": {...},
        "configuration-version": {...},
        "cost-estimate": {...},
        "created-by": {...},
        "input-state-version": {...},
        "plan": {...},
        "run-events": {...},
        "policy-checks": {...},
        "workspace": {...},
        "workspace-run-alerts": {...}
        }
      },
      "links": {
        "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7"
      }
    },
    {...}
  ]
}
{
  "data": [
    {
      "id": "run-CZcmD7eagjhyX0vN",
      "type": "runs",
      "attributes": {
        "actions": {
          "is-cancelable": true,
          "is-confirmable": false,
          "is-discardable": false,
          "is-force-cancelable": false
        },
        "canceled-at": null,
        "created-at": "2021-05-24T07:38:04.171Z",
        "has-changes": false,
        "auto-apply": false,
        "allow-empty-apply": false,
        "is-destroy": false,
        "message": "Custom message",
        "plan-only": false,
        "source": "tfe-api",
        "status-timestamps": {
          "plan-queueable-at": "2021-05-24T07:38:04+00:00"
        },
        "status": "pending",
        "trigger-reason": "manual",
        "target-addrs": null,
        "permissions": {
          "can-apply": true,
          "can-cancel": true,
          "can-comment": true,
          "can-discard": true,
          "can-force-execute": true,
          "can-force-cancel": true,
          "can-override-policy-check": true
        },
        "refresh": false,
        "refresh-only": false,
        "replace-addrs": null,
        "variables": []
      },
      "relationships": {
        "apply": {...},
        "comments": {...},
        "configuration-version": {...},
        "cost-estimate": {...},
        "created-by": {...},
        "input-state-version": {...},
        "plan": {...},
        "run-events": {...},
        "policy-checks": {...},
        "workspace": {...},
        "workspace-run-alerts": {...}
        }
      },
      "links": {
        "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7"
      }
    },
    {...}
  ]
}

»Get run details

GET /runs/:run_id

ParameterDescription
:run_idThe run ID to get.

This endpoint is used for showing details of a specific run.

StatusResponseReason
200JSON API document (type: "runs")Success
404JSON API error objectRun not found or user not authorized

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/runs/run-bWSq4YeYpfrW4mx7
curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/runs/run-bWSq4YeYpfrW4mx7

»Sample Response

{
  "data": {
    "id": "run-CZcmD7eagjhyX0vN",
    "type": "runs",
    "attributes": {
      "actions": {
        "is-cancelable": true,
        "is-confirmable": false,
        "is-discardable": false,
        "is-force-cancelable": false
      },
      "canceled-at": null,
      "created-at": "2021-05-24T07:38:04.171Z",
      "has-changes": false,
      "auto-apply": false,
      "allow-empty-apply": false,
      "is-destroy": false,
      "message": "Custom message",
      "plan-only": false,
      "source": "tfe-api",
      "status-timestamps": {
        "plan-queueable-at": "2021-05-24T07:38:04+00:00"
      },
      "status": "pending",
      "trigger-reason": "manual",
      "target-addrs": null,
      "permissions": {
        "can-apply": true,
        "can-cancel": true,
        "can-comment": true,
        "can-discard": true,
        "can-force-execute": true,
        "can-force-cancel": true,
        "can-override-policy-check": true
      },
      "refresh": false,
      "refresh-only": false,
      "replace-addrs": null,
      "variables": []
    },
    "relationships": {
      "apply": {...},
      "comments": {...},
      "configuration-version": {...},
      "cost-estimate": {...},
      "created-by": {...},
      "input-state-version": {...},
      "plan": {...},
      "run-events": {...},
      "policy-checks": {...},
      "task-stages": {...},
      "workspace": {...},
      "workspace-run-alerts": {...}
      }
    },
    "links": {
      "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7"
    }
  }
}
{
  "data": {
    "id": "run-CZcmD7eagjhyX0vN",
    "type": "runs",
    "attributes": {
      "actions": {
        "is-cancelable": true,
        "is-confirmable": false,
        "is-discardable": false,
        "is-force-cancelable": false
      },
      "canceled-at": null,
      "created-at": "2021-05-24T07:38:04.171Z",
      "has-changes": false,
      "auto-apply": false,
      "allow-empty-apply": false,
      "is-destroy": false,
      "message": "Custom message",
      "plan-only": false,
      "source": "tfe-api",
      "status-timestamps": {
        "plan-queueable-at": "2021-05-24T07:38:04+00:00"
      },
      "status": "pending",
      "trigger-reason": "manual",
      "target-addrs": null,
      "permissions": {
        "can-apply": true,
        "can-cancel": true,
        "can-comment": true,
        "can-discard": true,
        "can-force-execute": true,
        "can-force-cancel": true,
        "can-override-policy-check": true
      },
      "refresh": false,
      "refresh-only": false,
      "replace-addrs": null,
      "variables": []
    },
    "relationships": {
      "apply": {...},
      "comments": {...},
      "configuration-version": {...},
      "cost-estimate": {...},
      "created-by": {...},
      "input-state-version": {...},
      "plan": {...},
      "run-events": {...},
      "policy-checks": {...},
      "task-stages": {...},
      "workspace": {...},
      "workspace-run-alerts": {...}
      }
    },
    "links": {
      "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7"
    }
  }
}

»Discard a Run

POST /runs/:run_id/actions/discard

ParameterDescription
run_idThe run ID to discard

The discard action can be used to skip any remaining work on runs that are paused waiting for confirmation or priority. This includes runs in the "pending," "needs confirmation," "policy checked," and "policy override" states.

Discarding a run requires permission to apply runs for the workspace. (More about permissions.)

This endpoint queues the request to perform a discard; the discard might not happen immediately. After discarding, the run is completed and later runs can proceed.

This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body.

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

StatusResponseReason(s)
202noneSuccessfully queued a discard request.
409JSON API error objectRun was not paused for confirmation or priority; discard not allowed.

»Request Body

This POST endpoint allows an optional JSON object with the following properties as a request payload.

Key pathTypeDefaultDescription
commentstringnullAn optional explanation for why the run was discarded.

»Sample Payload

This payload is optional, so the curl command will work without the --data @payload.json option too.

{
  "comment": "This run was discarded"
}
{
  "comment": "This run was discarded"
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/discard
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/discard

»Cancel a Run

POST /runs/:run_id/actions/cancel

ParameterDescription
run_idThe run ID to cancel

The cancel action can be used to interrupt a run that is currently planning or applying. Performing a cancel is roughly equivalent to hitting ctrl+c during a Terraform plan or apply on the CLI. The running Terraform process is sent an INT signal, which instructs Terraform to end its work and wrap up in the safest way possible.

Canceling a run requires permission to apply runs for the workspace. (More about permissions.)

This endpoint queues the request to perform a cancel; the cancel might not happen immediately. After canceling, the run is completed and later runs can proceed.

This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body.

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

StatusResponseReason(s)
202noneSuccessfully queued a cancel request.
409JSON API error objectRun was not planning or applying; cancel not allowed.
404JSON API error objectRun was not found or user not authorized.

»Request Body

This POST endpoint allows an optional JSON object with the following properties as a request payload.

Key pathTypeDefaultDescription
commentstringnullAn optional explanation for why the run was canceled.

»Sample Payload

This payload is optional, so the curl command will work without the --data @payload.json option too.

{
  "comment": "This run was stuck and would never finish."
}
{
  "comment": "This run was stuck and would never finish."
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/cancel
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/cancel

»Forcefully cancel a run

POST /runs/:run_id/actions/force-cancel

ParameterDescription
run_idThe run ID to cancel

The force-cancel action is like cancel, but ends the run immediately. Once invoked, the run is placed into a canceled state, and the running Terraform process is terminated. The workspace is immediately unlocked, allowing further runs to be queued. The force-cancel operation requires admin access to the workspace. (More about permissions.)

This endpoint enforces a prerequisite that a non-forceful cancel is performed first, and a cool-off period has elapsed. To determine if this criteria is met, it is useful to check the data.attributes.is-force-cancelable value of the run details endpoint. The time at which the force-cancel action will become available can be found using the run details endpoint, in the key data.attributes.force_cancel_available_at. Note that this key is only present in the payload after the initial cancel has been initiated.

This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body.

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

Warning: This endpoint has potentially dangerous side-effects, including loss of any in-flight state in the running Terraform process. Use this operation with extreme caution.

StatusResponseReason(s)
202noneSuccessfully queued a cancel request.
409JSON API error objectRun was not planning or applying, has not been canceled non-forcefully, or the cool-off period has not yet passed.
404JSON API error objectRun was not found or user not authorized.

»Request Body

This POST endpoint allows an optional JSON object with the following properties as a request payload.

Key pathTypeDefaultDescription
commentstringnullAn optional explanation for why the run was canceled.

»Sample Payload

This payload is optional, so the curl command will work without the --data @payload.json option too.

{
  "comment": "This run was stuck and would never finish."
}
{
  "comment": "This run was stuck and would never finish."
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/force-cancel
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/force-cancel

»Forcefully execute a run

POST /runs/:run_id/actions/force-execute

ParameterDescription
run_idThe run ID to execute

The force-execute action cancels all prior runs that are not already complete, unlocking the run's workspace and allowing the run to be executed. (It initiates the same actions as the "Run this plan now" button at the top of the view of a pending run.)

Force-executing a run requires permission to apply runs for the workspace. (More about permissions.)

This endpoint enforces the following prerequisites:

  • The target run is in the "pending" state.
  • The workspace is locked by another run.
  • The run locking the workspace can be discarded.

This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body.

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

Note: While useful at times, force-executing a run circumvents the typical workflow of applying runs using Terraform Cloud. It is not intended for regular use. If you find yourself using it frequently, please reach out to HashiCorp Support for help in developing an alternative approach.

StatusResponseReason(s)
202noneSuccessfully initiated the force-execution process.
403JSON API error objectRun is not pending, its workspace was not locked, or its workspace association was not found.
409JSON API error objectThe run locking the workspace was not in a discardable state.
404JSON API error objectRun was not found or user not authorized.

»Request Body

This POST endpoint does not take a request body.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/force-execute
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/force-execute

»Available Related Resources

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

  • plan - Additional information about plans.
  • apply - Additional information about applies.
  • created_by - Full user records of the users responsible for creating the runs.
  • cost_estimate - Additional information about cost estimates.
  • configuration_version - The configuration record used in the run.
  • configuration_version.ingress_attributes - The commit information used in the run.
github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager