Stack deployments API reference

You can create Stack deployments in a Stack's deployment.tfdeploy.hcl file. A deployment consists of a deployment group, at least one deployment run, and at least one deployment step. To learn more, refer to Define deployment configuration.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`GET`	`/stacks/:stack_id/stack-deployments`	Call this endpoint to list Stack deployments.
`GET`	`/stack-configurations/:stack_configuration_id/stack-deployment-groups`	Call this endpoint to list Stack deployment groups.
`GET`	`/stack-configurations/:stack_configuration_id/stack-deployment-groups/:stack_deployment_group_name`	Call this endpoint to show a Stack deployment group by name.
`GET`	`/stack-deployment-groups/:stack_deployment_group_id`	Call this endpoint to show a Stack deployment group by ID.
`GET`	`/stack-configurations/:stack_configuration_id/stack-deployment-runs`	Call this endpoint to list Stack deployment runs in a configuration.
`GET`	`/stack-deployment-groups/:stack_deployment_group_id/stack-deployment-runs`	Call this endpoint to list Stack deployment runs in a group.
`GET`	`/stack-deployment-runs/:stack_deployment_run_id`	Call this endpoint to show a Stack deployment run.
`GET`	`/stack-deployment-runs/:stack_deployment_run_id/stack-deployment-steps`	Call this endpoint to list Stack deployment steps.
`GET`	`/stack-deployment-steps/:stack_deployment_step_id`	Call this endpoint to show a Stack deployment step.
`GET`	`/stack-deployment-steps/:stack_deployment_step_id/stack-diagnostics`	Call this endpoint to list Stack deployment step diagnostics.
`GET`	`/stack-deployment-steps/:stack_deployment_step_id/artifacts`	Call this endpoint to retrieve a Stack deployment step artifact.
`GET`	`/stack-approvals/:stack_approval_id`	Call this endpoint to show a Stack approval.
`POST`	`/stack-deployment-groups/:stack_deployment_group_id/approve-all-plans`	Call this endpoint to approve a Stack deployment group.
`POST`	`/stack-deployment-groups/:stack_deployment_group_id/rerun`	Call this endpoint to rerun a Stack deployment group.
`POST`	`/stack-deployment-groups/:stack_deployment_group_id/start`	Call this endpoint to start a Stack deployment group.
`POST`	`/stack-deployment-groups/:stack_deployment_group_id/cancel`	Call this endpoint to cancel a Stack deployment group.
`POST`	`/stack-deployment-runs/:stack_deployment_run_id/approve-all-plans`	Call this endpoint to approve a Stack deployment run.
`POST`	`/stack-deployment-runs/:stack_deployment_run_id/cancel`	Call this endpoint to cancel a Stack deployment run.
`POST`	`/stack-deployment-steps/:stack_deployment_step_id/advance`	Call this endpoint to advance a Stack deployment step.

List Stack deployments

This endpoint lists all the deployments under the specified Stack.

GET /stacks/:stack_id/stack-deployments

Parameter	Description
`:stack_id`	The id of the Stack to list deployments for.

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.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stacks deployments per page.
`q`	Optional. Search by deployment name. This search is case-insensitive.
`sort`	Optional. Sort by deployment name. Accepted values are "deployment" (ascending) and "-deployment" (descending).

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

Resource Name	Description
`latest_deployment_run`	The latest deployment run associated with that deployment.
`latest_deployment_run.stack_configuration`	The Stack configuration associated with the latest deployment run.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt/stack-deployments

Sample Response

{
  "data": [
    {
      "id": "st-MWvJsvy1FCg3bnXY-std-simple",
      "type": "stack-deployments",
      "attributes": {
        "name": "simple"
      },
      "relationships": {
        "stack": {
          "data": {
            "id": "st-MWvJsvy1FCg3bnXY",
            "type": "stacks"
          }
        },
        "latest-deployment-run": {
          "data": {
            "id": "sdr-vzub48Y4f7sFBk7J",
            "type": "stack-deployment-runs"
          }
        }
      },
      "links": {
        "self": "/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments/simple",
        "stack-deployment-runs": "/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments/simple/stack-deployment-runs"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

List Stack deployment groups

This endpoint lists all the deployment groups for the specified Stack configuration.

GET /stack-configurations/:stack_configuration_id/stack-deployment-groups

Parameter	Description
`:stack_configuration_id`	The id of the Stack configuration to list deployment groups for.

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.

Parameter	Description
`filter[status]`	Optional. Filters results to groups matching one or more of the specified statuses. Accepts a comma-separated list.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stack deployment groups per page.
`q`	Optional. Search by group name. This search is case-insensitive.
`sort`	Optional. Sort by group `name` or `status-priority`. Prefix with `-` to reverse order. `status-priority` orders groups from highest to lowest: failed, deploying, pre-deploying, pending, abandoned, succeeded.

To retrieve related resources, you can optionally add the include query parameter when making GET requests. The following resource types are available:

Resource Name	Description
`stack_deployment_group_summary`	A summary of the current statuses for the group's deployment runs.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-groups

Sample Response

{
  "data": [
    {
      "id": "sdg-56aAuyFSwfD12Wna",
      "type": "stack-deployment-groups",
      "attributes": {
        "status": "succeeded",
        "created-at": "2026-07-09T19:10:00.513Z",
        "updated-at": "2026-07-09T19:10:18.917Z",
        "deploying-at": "2026-07-09T19:10:11.083Z",
        "succeeded-at": "2026-07-09T19:10:18.915Z",
        "failed-at": null,
        "abandoned-at": null,
        "name": "complex_default",
        "deployment-group-config": {
          "auto-approve-checks": [],
          "eager-plan": "on",
          "failure-tolerance": null,
          "custom": false
        }
      },
      "relationships": {
        "stack-configuration": {
          "data": {
            "id": "stc-EGBivHirPGeTRoeL",
            "type": "stack-configurations"
          }
        },
        "stack-approvals": {
          "data": []
        },
        "stack-deployment-runs": {
          "links": {
            "related": "/api/v2/stack-deployment-groups/sdg-56aAuyFSwfD12Wna/stack-deployment-runs"
          }
        },
        "stack-deployment-group-summary": {
          "data": {
            "id": "sdg-56aAuyFSwfD12Wna-summary",
            "type": "stack-deployment-group-summaries"
          }
        },
        "run-status-summaries": {
          "data": {
            "id": "sdg-56aAuyFSwfD12Wna-summary",
            "type": "stack-deployment-group-summaries"
          }
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-groups/sdg-56aAuyFSwfD12Wna",
        "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-EGBivHirPGeTRoeL/stack-deployment-group-summaries"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-configurations/stc-EGBivHirPGeTRoeL/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-configurations/stc-EGBivHirPGeTRoeL/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-configurations/stc-EGBivHirPGeTRoeL/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a Stack deployment group by name

This endpoint gets details about a Stack deployment group by name.

GET /stack-configurations/:stack_configuration_id/stack-deployment-groups/:stack_deployment_group_name

Parameter	Description
`:stack_configuration_id`	The id of the Stack configuration to fetch the deployment groups for.
`:stack_deployment_group_name`	The Stack deployment group name.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-groups/simple_default

Sample Response

{
  "data": {
    "id": "sdg-56aAuyFSwfD12Wna",
    "type": "stack-deployment-groups",
    "attributes": {
      "status": "succeeded",
      "created-at": "2026-07-09T19:10:00.513Z",
      "updated-at": "2026-07-09T19:10:18.917Z",
      "deploying-at": "2026-07-09T19:10:11.083Z",
      "succeeded-at": "2026-07-09T19:10:18.915Z",
      "failed-at": null,
      "abandoned-at": null,
      "name": "complex_default",
      "deployment-group-config": {
        "auto-approve-checks": [],
        "eager-plan": "on",
        "failure-tolerance": null,
        "custom": false
      }
    },
    "relationships": {
      "stack-configuration": {
        "data": {
          "id": "stc-EGBivHirPGeTRoeL",
          "type": "stack-configurations"
        }
      },
      "stack-approvals": {
        "data": []
      },
      "stack-deployment-runs": {
        "links": {
          "related": "/api/v2/stack-deployment-groups/sdg-56aAuyFSwfD12Wna/stack-deployment-runs"
        }
      },
      "stack-deployment-group-summary": {
        "data": {
          "id": "sdg-56aAuyFSwfD12Wna-summary",
          "type": "stack-deployment-group-summaries"
        }
      },
      "run-status-summaries": {
        "data": {
          "id": "sdg-56aAuyFSwfD12Wna-summary",
          "type": "stack-deployment-group-summaries"
        }
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-groups/sdg-56aAuyFSwfD12Wna",
      "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-EGBivHirPGeTRoeL/stack-deployment-group-summaries"
    }
  }
}

Show a Stack deployment group by ID

This endpoint gets details about a Stack deployment group by ID.

GET /stack-deployment-groups/:stack_deployment_group_id

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group to fetch.

To retrieve related resources, you can optionally add the include query parameter when making GET requests. The following resource types are available:

Resource Name	Description
`stack_deployment_group_summary`	A summary of the current statuses for the group's deployment runs.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7

Sample Response

{
  "data": {
    "id": "sdg-56aAuyFSwfD12Wna",
    "type": "stack-deployment-groups",
    "attributes": {
      "status": "succeeded",
      "created-at": "2026-07-09T19:10:00.513Z",
      "updated-at": "2026-07-09T19:10:18.917Z",
      "deploying-at": "2026-07-09T19:10:11.083Z",
      "succeeded-at": "2026-07-09T19:10:18.915Z",
      "failed-at": null,
      "abandoned-at": null,
      "name": "complex_default",
      "deployment-group-config": {
        "auto-approve-checks": [],
        "eager-plan": "on",
        "failure-tolerance": null,
        "custom": false
      }
    },
    "relationships": {
      "stack-configuration": {
        "data": {
          "id": "stc-EGBivHirPGeTRoeL",
          "type": "stack-configurations"
        }
      },
      "stack-approvals": {
        "data": []
      },
      "stack-deployment-runs": {
        "links": {
          "related": "/api/v2/stack-deployment-groups/sdg-56aAuyFSwfD12Wna/stack-deployment-runs"
        }
      },
      "stack-deployment-group-summary": {
        "data": {
          "id": "sdg-56aAuyFSwfD12Wna-summary",
          "type": "stack-deployment-group-summaries"
        }
      },
      "run-status-summaries": {
        "data": {
          "id": "sdg-56aAuyFSwfD12Wna-summary",
          "type": "stack-deployment-group-summaries"
        }
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-groups/sdg-56aAuyFSwfD12Wna",
      "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-EGBivHirPGeTRoeL/stack-deployment-group-summaries"
    }
  }
}

List Stack deployment runs in a configuration

This endpoint lists Stack deployment runs for a Stack configuration.

GET /stack-configurations/:stack_configuration_id/stack-deployment-runs

Parameter	Description
`:stack_configuration_id`	The id of the Stack deployment group for which Stack deployment runs are being listed.

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.

Parameter	Description
`filter[latest_only]`	Optional. When set to `true`, returns only the latest run for each deployment within the configuration.
`filter[status]`	Optional. When set to `true`, returns only runs matching one or more of the specified statuses. Accepts a comma-separated list. The following statuses each map to multiple underlying run states: `pending` (pending, acquiring-lock, pending-capacity), `running` (pre-deploying, deploying), and `pending-operator` (pre-deploying-pending-operator, deploying-pending-operator).
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stack deployment runs per page.
`q`	Optional. Search by deployment name or group name. This search is case-insensitive.
`sort`	Optional. Sort by `deployment` (deployment name) or `deployment-group-name`. Prefix with `-` to reverse order.

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

Resource Name	Description
`current_step`	The current step for the deployment run.
`destroy_stack_configuration`	The configuration that last referenced a deployment that has been omitted in the configuration that contains the specified run.
`stack_approval`	The Stack approval created for the deployment run.
`stack_deployment_group`	The deployment group that contains the run.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-runs

Sample Response

{
  "data": [
    {
      "id": "sdr-AUkZBKdkE9vRKDsi",
      "type": "stack-deployment-runs",
      "attributes": {
        "status": "pre_deploying_pending_operator",
        "deployment": "simple",
        "created-at": "2025-09-16T14:46:45.032Z",
        "updated-at": "2025-09-16T14:46:45.121Z",
        "pre-deploying-at": "2025-09-16T14:46:45.067Z",
        "pre-deploying-pending-operator-at": "2025-09-16T14:46:45.121Z",
        "acquiring-lock-at": null,
        "deploying-at": null,
        "deploying-pending-operator-at": null,
        "succeeded-at": null,
        "failed-at": null,
        "abandoned-at": null,
        "plan-mode": "plan"
      },
      "relationships": {
        "stack-deployment-group": {
          "data": {
            "id": "sdg-f5GVSZb7HxQ5aWG7",
            "type": "stack-deployment-groups"
          }
        },
        "stack-configuration": {
          "data": {
            "id": "stc-d7w6uC1QEB6fqWjW",
            "type": "stack-configurations"
          }
        },
        "stack-deployment-steps": {
          "links": {
            "related": "/api/v2/stack-deployment-runs/sdr-AUkZBKdkE9vRKDsi/stack-deployment-steps"
          }
        },
        "stack-approval": {
          "data": null
        },
        "current-step": {
          "data": {
            "id": "sds-HQuuzLYg8rcPSbRt",
            "type": "stack-deployment-steps"
          }
        },
        "destroy-stack-configuration": {
          "data": null
        },
        "latest-deployment-run-for-deployment": {
          "data": null
        },
        "blocked-by-deployment-group": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-runs/sdr-AUkZBKdkE9vRKDsi"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "status-counts": {
      "total": 1
    },
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

List Stack deployment runs in a group

This endpoint lists Stack deployment runs for a Stack deployment group.

GET /stack-deployment-groups/:stack_deployment_group_id/stack-deployment-runs

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group for which Stack deployment runs are being listed.

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.

Parameter	Description
`filter[latest_only]`	Optional. When set to `true`, returns only the latest run for each deployment within the group.
`filter[status]`	Optional. When set to `true`, returns only runs matching one or more of the specified statuses. Accepts a comma-separated list. The following statuses each map to multiple underlying run states: `failed`, `pending-operator` (pre-deploying-pending-operator, deploying-pending-operator), `running` (pre-deploying, deploying), `pending` (pending, acquiring-lock, pending-capacity), `abandoned`, `succeeded`.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stack deployment runs per page.
`q`	Optional. Search by deployment name. This search is case-insensitive.
`sort`	Optional. Sort by group `name` or `status-priority`. Prefix with `-` to reverse order. `status-priority` orders groups from highest to lowest: failed, deploying, deploying-pending-operator, pre-deploying, pre-deploying-pending-operator, acquiring-lock, pending-capacity, pending, abandoned, succeeded.

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

Resource Name	Description
`blocked_by_deployment_group`	The deployment group that is blocking this run from proceeding.
`current_step`	The current step for the deployment run.
`destroy_stack_configuration`	The configuration that last referenced a deployment that has been omitted in the configuration that contains the specified run.
`stack_approval`	The Stack approval created for the deployment run.
`stack_deployment_group`	The deployment group that contains the run.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs

Sample Response

{
  "data": [
    {
      "id": "sdr-A7Ly5aDFHUepLeF7",
      "type": "stack-deployment-runs",
      "attributes": {
        "status": "pre_deploying_pending_operator",
        "deployment": "simple",
        "created-at": "2025-09-11T15:33:25.141Z",
        "updated-at": "2025-09-11T15:33:33.390Z",
        "pre-deploying-at": "2025-09-11T15:33:25.273Z",
        "pre-deploying-pending-operator-at": "2025-09-11T15:33:33.390Z",
        "acquiring-lock-at": null,
        "deploying-at": null,
        "deploying-pending-operator-at": null,
        "succeeded-at": null,
        "failed-at": null,
        "abandoned-at": null,
        "plan-mode": "normal"
      },
      "relationships": {
        "stack-deployment-group": {
          "data": {
            "id": "sdg-LwBSiWxcrjhYBGMK",
            "type": "stack-deployment-groups"
          }
        },
        "stack-configuration": {
          "data": {
            "id": "stc-jEvHkd8DXBK594WD",
            "type": "stack-configurations"
          }
        },
        "stack-deployment-steps": {
          "links": {
            "related": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7/stack-deployment-steps"
          }
        },
        "stack-approval": {
          "data": null
        },
        "current-step": {
          "data": {
            "id": "sds-qbXEc9fNpt7MNpKT",
            "type": "stack-deployment-steps"
          }
        },
        "destroy-stack-configuration": {
          "data": null
        },
        "latest-deployment-run-for-deployment": {
          "data": null
        },
        "blocked-by-deployment-group": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-deployment-groups/sdg-LwBSiWxcrjhYBGMK/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-deployment-groups/sdg-LwBSiWxcrjhYBGMK/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-deployment-groups/sdg-LwBSiWxcrjhYBGMK/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a Stack deployment run

This endpoint gets details about a Stack deployment run.

GET /stack-deployment-runs/:stack_deployment_run_id

Parameter	Description
`:stack_deployment_run_id`	The id of the Stack deployment run to show.

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

Resource Name	Description
`stack_deployment_group`	The deployment group that contains the run.
`stack_approval`	The Stack approval created for the deployment run.
`destroy_stack_configuration`	The configuration that last referenced a deployment that has been omitted in the configuration that contains the specified run.
`blocked_by_deployment_group`	The deployment group that is blocking this run from proceeding.
`latest_deployment_run_for_deployment`	The latest deployment run for the deployment that the current run is targeting.
`current_step`	The current step for the deployment run.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-runs/sdr-LSqektntTNJrAhCt

Sample Response

{
  "data": {
    "id": "sdr-A7Ly5aDFHUepLeF7",
    "type": "stack-deployment-runs",
    "attributes": {
      "status": "pre_deploying_pending_operator",
      "deployment": "simple",
      "created-at": "2025-09-11T15:33:25.141Z",
      "updated-at": "2025-09-11T15:33:33.390Z",
      "pre-deploying-at": "2025-09-11T15:33:25.273Z",
      "pre-deploying-pending-operator-at": "2025-09-11T15:33:33.390Z",
      "acquiring-lock-at": null,
      "deploying-at": null,
      "deploying-pending-operator-at": null,
      "succeeded-at": null,
      "failed-at": null,
      "abandoned-at": null,
      "plan-mode": "normal"
    },
    "relationships": {
      "stack-deployment-group": {
        "data": {
          "id": "sdg-LwBSiWxcrjhYBGMK",
          "type": "stack-deployment-groups"
        }
      },
      "stack-configuration": {
        "data": {
          "id": "stc-jEvHkd8DXBK594WD",
          "type": "stack-configurations"
        }
      },
      "stack-deployment-steps": {
        "links": {
          "related": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7/stack-deployment-steps"
        }
      },
      "stack-approval": {
        "data": null
      },
      "current-step": {
        "data": {
          "id": "sds-qbXEc9fNpt7MNpKT",
          "type": "stack-deployment-steps"
        }
      },
      "destroy-stack-configuration": {
        "data": null
      },
      "latest-deployment-run-for-deployment": {
        "data": {
          "id": "sdr-A7Ly5aDFHUepLeF7",
          "type": "stack-deployment-runs"
        }
      },
      "blocked-by-deployment-group": {
        "data": null
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7"
    }
  }
}

List Stack deployment steps

This endpoint lists Stack deployment steps for a Stack deployment run.

GET /stack-deployment-runs/:stack_deployment_run_id/stack-deployment-steps

Parameter	Description
`:stack_deployment_run_id`	The id of the Stack deployment run for which Stack deployment steps are being listed.

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.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stack deployment steps runs per page.
`sort`	Optional. Sort by step order. Prefix with `-` to reverse order.

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

Resource Name	Description
`stack_approval`	The approval associated with the specified step.
`stack_approval.user`	The user that created the approval for the specified step.
`stack_state`	The state that was created as the result of an apply operation from the specified step.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps

Sample Response

{
  "data": [
    {
      "id": "sds-c8qjj4urpyh1wFrU",
      "type": "stack-deployment-steps",
      "attributes": {
        "status": "pending_operator",
        "operation-type": "plan",
        "requires-state-lock": false,
        "created-at": "2025-09-10T21:22:31.577Z",
        "updated-at": "2025-09-11T17:38:13.903Z",
        "queued-at": "2025-09-10T21:22:31.606Z",
        "running-at": "2025-09-10T21:22:32.797Z",
        "pending-operator-at": "2025-09-10T21:22:39.862Z",
        "completed-at": null,
        "failed-at": null,
        "abandoned-at": null
      },
      "relationships": {
        "stack-deployment-run": {
          "data": {
            "id": "sdr-qreEJHTfJ9i3qooa",
            "type": "stack-deployment-runs"
          }
        },
        "stack-diagnostics": {
          "links": {
            "related": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/stack-diagnostics"
          },
          "meta": {
            "count": 0
          }
        },
        "stack-approval": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU",
        "plan-description": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/artifacts?name=plan-description",
        "structured-log": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6QUFxZHhyS2xHcjA0MzVvbWhXOTVXU1gwQW1MS2hVNiszcHRLd01RZWgxT3phMmdJMWo0RC8xT1liWGZBaFFhalF2NG11R3dmdndIdnBmWWsyeWQzYnlnUW1sYjdTRm5rM1BjMlN0dVFXZWJMbmtkeWVaamMvYkhMcjZzLytvVVpJc3NtVFpJSng5MVVrTmd3eWNKM2JWd1ZNUXVUZWR3bzRHSU5qb3JzWW5FeEE0WlJlTHJySFlQMzJhMmRaSUJKMU5GYy9kQUJwOCs3M1k1WEhNa0o1VTdPK1FwRmYwVThqdkx1eklNQzVuYXphOUVBRTZzYUlERk1Pc3JXWnpwRnFYR3BGTGZleGNNSE1RVE0yTGVseFhkd3M0Ymo5ZkV4RXVZTUdrR0ZId215d2U3SllwaGFhRkUvT2VRUTVlTmZoUGp1SklxVkhTZ05IRktlVDNCeEN3UVpCUDlHRnpveUwrWTZ6aW81ZVM1YUM0QVZvV1BUMDA0WkF4VmtwTDVRclVRPQ"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-deployment-runs/sdr-qreEJHTfJ9i3qooa/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-deployment-runs/sdr-qreEJHTfJ9i3qooa/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-deployment-runs/sdr-qreEJHTfJ9i3qooa/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a Stack deployment step

This endpoint gets details about a Stack deployment step.

GET /stack-deployment-steps/:stack_deployment_step_id

Parameter	Description
`:stack_deployment_step_id`	The id of the Stack deployment step to show.

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

Resource Name	Description
`stack_approval`	The approval associated with the specified step.
`stack_approval.user`	The user that created the approval for the specified step.
`stack_state`	The state that was created as the result of an apply operation from the specified step.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt

Sample Response

{
  "data": {
    "id": "sds-c8qjj4urpyh1wFrU",
    "type": "stack-deployment-steps",
    "attributes": {
      "status": "pending_operator",
      "operation-type": "plan",
      "requires-state-lock": false,
      "created-at": "2025-09-10T21:22:31.577Z",
      "updated-at": "2025-09-11T17:38:13.903Z",
      "queued-at": "2025-09-10T21:22:31.606Z",
      "running-at": "2025-09-10T21:22:32.797Z",
      "pending-operator-at": "2025-09-10T21:22:39.862Z",
      "completed-at": null,
      "failed-at": null,
      "abandoned-at": null
    },
    "relationships": {
      "stack-deployment-run": {
        "data": {
          "id": "sdr-qreEJHTfJ9i3qooa",
          "type": "stack-deployment-runs"
        }
      },
      "stack-diagnostics": {
        "links": {
          "related": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/stack-diagnostics"
        },
        "meta": {
          "count": 0
        }
      },
      "stack-approval": {
        "data": null
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU",
      "plan-description": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/artifacts?name=plan-description",
      "structured-log": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6dHAxbFAwTHRXK3FQRFRxWklXd2E1UG0yc1JLQ3JsNVJheUNZR2l5ak9EYy9XOHk3RmdqSGw4VEswUmJDTFBCNlEvSEgvRHhhb0FCRVBmKytCRHV4TktENEFJRytWT3dXVjdTR2ZuRkFRODdEOUtuN08vdzQvRGdEcXVmb0xINHR5QlJZRnB3L1ZmRmY3blk3Q3dub1hCUmVXMW9uZUxLUUdyZGQzUWpLS3M0S0dMMTNiN3ZGRnFrQ3NoSjVKeXE4WS9iTzd6anA2MHZkWitUZ2hEcndZcTBZK0M5dFFrQkZzWjdoTUJhdS9ja3VMb3M5OFZBa0k2WjJBSHh3T2NCRjBLdjNlRThRUDBqOStrVWYxWXQ2VllTUzUzQ1YxNUkvUUJyY09CeUFsOGtrSVlMTWdFWkErM1g4NmN4UEQ3emFHZDAwUnJOa0xyQmd3VERiRGF4ZTRiMzdNVFZkcFFFWlZBMzJOcDloOWZ3U1pTMjY0Y0M4enUwdUp6WmZUditVZjk4PQ"
    }
  }
}

List Stack deployment step diagnostics

This endpoint lists Stack deployment step diagnostics for a Stack deployment step.

GET /stack-deployment-steps/:stack_deployment_step_id/stack-diagnostics

Parameter	Description
`:stack_deployment_step_id`	The id of the Stack deployment step for which Stack deployment diagnostics are being listed.

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.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stack deployment step diagnostics per page.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics

Sample Response

{
  "data": [
    {
      "id": "stf-PrqektntTNJrAhCm",
      "type": "stack-diagnostics",
      "attributes": {
        "severity": "warning",
        "summary": "Diagnostics reported",
        "detail": "While preparing the configuration, HCP Terraform reported 2 warnings.",
        "diags": null,
        "acknowledged": true,
        "acknowledged-at": "2025-06-11T06:13:01.082Z",
        "created-at": "2025-06-11T06:13:01.082Z"
      },
      "links": {
        "self": "/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics"
      },
      "relationships": {
       "stack-configuration": {
          "data": {
            "id": "stc-RSqektntTNJrAhCm",
            "type": "stack-configurations"
          }
        },
        "stack-deployment-step": {
          "data": {
            "id": "sds-qB6dJk7G7r7icTE8",
            "type": "stack-deployment-steps"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a Stack deployment step artifact

This endpoint returns an archivist URL for the requested artifact of a specified deployment step.

GET /stack-deployment-steps/:stack_deployment_step_id/artifacts

Parameter	Description
`:stack_deployment_step_id`	The id of the Stack deployment step for which the artifacts are requested.

Query Parameters

These are standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`name`	Required. The name of the particular artifact being requested. Acceptable values are `plan-description`, `plan-debug-log`, `apply-description`, and `apply-debug-log`.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/name=plan-description

Show a Stack approval

This endpoint gets details about a Stack approval.

GET /stack-approvals/:stack_approval_id

Parameter	Description
`:stack_approval_id`	The id of the Stack approval to show.

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

Resource Name	Description
`user`	The user that created the specified Stack approval.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-approvals/sta-LSqektntTNJrAhCt

Sample Response

{
  "data": {
    "id": "sa-6jJFPnNyEUSLLGhh",
    "type": "stack-approvals",
    "attributes": {
      "reason": null,
      "created-at": "2025-09-16T14:25:02.485Z"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "user-zqE1r5BwBu9rVLAR",
          "type": "users"
        }
      }
    }
  }
}

Approve a Stack deployment group

This endpoint creates a global approval for all runs in a Stack deployment group.

POST /stack-deployment-groups/:stack_deployment_group_id/approve-all-plans

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group to approve.

Status	Response	Reason
204	No Content	Successfully approved all plans for the Stack deployment group.
404	JSON API error object	Stack deployment group not found, or user unauthorized to perform action.

Request Body

This POST endpoint will optionally accept a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`reason`	string	""	The reason for the approval.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/approve-all-plans

Rerun a Stack deployment group

This endpoint reruns a Stack deployment group that has ended up in a failed state.

POST /stack-deployment-groups/:stack_deployment_group_id/rerun

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group to rerun.

Status	Response	Reason
204	No Content	Successfully reran the Stack deployment group.
404	JSON API error object	Stack deployment group not found, or user unauthorized to perform action.
409	JSON API error object	The `deployments` query parameter is present but empty.
422	JSON API error object	One or more of the specified deployments are not in a failed or abandoned state.

Query Parameters

This endpoint requires the usage of query parameters to specify which deployments within the group must be rerun.

Parameter	Description
`deployments`	Optional. A comma-separated list specifying the names of the deployments within the group that are to be rerun. If omitted, all failed or abandoned deployments will be rerun. If present, all requested deployments must be failed or abandoned.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/rerun

Start a Stack deployment group

This endpoint starts planning all runs in a Stack deployment group that has eager plan disabled.

POST /stack-deployment-groups/:stack_deployment_group_id/start

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group to start.

Status	Response	Reason
202	None	Successfully started planning the Stack deployment group.
404	JSON API error object	Stack deployment group 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/stack-deployment-groups/stg-LSqektntTNJrAhCt/start

Cancel a Stack deployment group

This endpoint cancels a Stack deployment group.

POST /stack-deployment-groups/:stack_deployment_group_id/cancel

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group to cancel.

Status	Response	Reason
202	None	Successfully cancels the Stack deployment group.
404	JSON API error object	Stack deployment group not found, or user unauthorized to perform action.
409	JSON API error object	Stack deployment group is in a terminal state and cannot be canceled.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/cancel

Approve a Stack deployment run

This endpoint approves all current and future plans associated with a Stack deployment run.

POST /stack-deployment-runs/:stack_deployment_run_id/approve-all-plans

Parameter	Description
`:stack_deployment_run_id`	The id of the Stack deployment run to approve.

Status	Response	Reason
204	No Content	Successfully approved all plans for the Stack deployment run.
404	JSON API error object	Stack deployment run not found, or user unauthorized to perform action.

Request Body

This POST endpoint will optionally accept a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`reason`	string	""	The reason for the approval.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-runs/sdr-LSqektntTNJrAhCt/approve-all-plans

Cancel a Stack deployment run

This endpoint cancels a Stack deployment run.

POST /stack-deployment-runs/:stack_deployment_run_id/cancel

Parameter	Description
`:stack_deployment_run_id`	The id of the Stack deployment run to cancel.

Status	Response	Reason
202	None	Successfully canceled the Stack deployment run.
404	JSON API error object	Stack deployment run 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/stack-deployment-runs/sdr-LSqektntTNJrAhCt/cancel

Advance a Stack deployment step

This endpoint advances a Stack deployment step.

POST /stack-deployment-steps/:stack_deployment_step_id/advance

Parameter	Description
`:stack_deployment_step_id`	The id of the Stack deployment step to advance.

Status	Response	Reason
204	No Content	Successfully advanced the Stack deployment step.
404	JSON API error object	Stack deployment step not found, or user unauthorized to perform action.

Request Body

This POST endpoint will optionally accept a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`reason`	string	""	The reason for the advancement.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/advance

Stack deployments API reference

Overview

List Stack deployments

Query Parameters

Available Related Resources

Sample Request

Sample Response

List Stack deployment groups

Query Parameters

Available Related Resources

Sample Request

Sample Response

Show a Stack deployment group by name

Sample Request

Sample Response

Show a Stack deployment group by ID

Available Related Resources

Sample Request

Sample Response

List Stack deployment runs in a configuration

Query Parameters

Available Related Resources

Sample Request

Sample Response

List Stack deployment runs in a group

Query Parameters

Available Related Resources

Sample Request

Sample Response

Show a Stack deployment run

Available Related Resources

Sample Request

Sample Response

List Stack deployment steps

Query Parameters

Available Related Resources

Sample Request

Sample Response

Show a Stack deployment step

Available Related Resources

Sample Request

Sample Response

List Stack deployment step diagnostics

Query Parameters

Sample Request

Sample Response

Show a Stack deployment step artifact

Query Parameters

Sample Request

Show a Stack approval

Available Related Resources

Sample Request

Sample Response

Approve a Stack deployment group

Request Body

Sample Request

Rerun a Stack deployment group

Query Parameters

Sample Request

Start a Stack deployment group

Sample Request

Cancel a Stack deployment group

Sample Request

Approve a Stack deployment run

Request Body

Sample Request

Cancel a Stack deployment run

Sample Request

Advance a Stack deployment step

Request Body

Sample Request