Runs API reference

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.

Run Operations

The run operation specifies the Terraform execution mode. You can reference the following list of possible execution modes and use them as query parameters in the workspace and organization runs lists.

Run Sources

You can use the following sources as query parameters in workspace and organization runs lists.

Run Status Groups

The run status group specifies a collection of run states by logical category.

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.

Setting debugging_mode: true enables debugging mode for the queued run only. This is equivalent to setting the TF_LOG environment variable to TRACE for this run. See Debugging Terraform for more information.

Sample Run Variables:

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

Request Body

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

Properties without a default value are required.

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"
        }
      }
    }
  }
}

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

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,
      "allow-config-generation": 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,
      "save-plan": false,
      "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

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.

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.

Request Body

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

Sample Payload

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

{
  "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

List Runs in a Workspace

GET /workspaces/:workspace_id/runs

By default, plan_only runs will be excluded from the results. To see all runs, use filter[operation] with all available operations included as a comma-separated list. This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second.

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.

Sample Request

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,
        "allow-config-generation": 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,
        "save-plan": false,
        "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"
      }
    },
    {...}
  ]
}

List Runs in an Organization

GET /organizations/:organization_name/runs

This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second.

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.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/hashicorp/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,
        "allow-config-generation": 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,
        "save-plan": false,
        "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

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

Sample Request

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,
      "allow-config-generation": 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,
      "save-plan": false,
      "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

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.

Request Body

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

Sample Payload

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

{
  "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

Cancel a Run

POST /runs/:run_id/actions/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.

Request Body

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

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."
}

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

Forcefully cancel a run

POST /runs/:run_id/actions/force-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.

Request Body

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

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."
}

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

Forcefully execute a run

POST /runs/:run_id/actions/force-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.

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

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.