HashiDays One conference. Three cities. Find a city near you
Terraform
Terraform Home

Run task stages and results API reference

HCP Terraform uses run task stages and run task results to track run task execution.

Note: HCP Terraform Free Edition includes one run task integration that you can apply to up to ten workspaces. Refer to HCP Terraform pricing for details.

When HCP Terraform creates a run, it reads the run tasks associated to the workspace. Each run task in the workspace is configured to begin during a specific run stage. HCP Terraform creates a run task stage object for each run stage that triggers run tasks. You can configure run tasks during the Pre-Plan Stage, Post-Plan Stage, Pre-Apply Stage and Post-Apply Stage.

Run task stages then create a run task result for each run task. For example, a workspace has two run tasks called alpha and beta. For each run, HCP Terraform creates one run task stage called post-plan. That run task stage has two run task results: one for the alpha run task and one for the beta run task.

This page lists the endpoints to retrieve run task stages and run task results. Refer to the Run Tasks API for endpoints to create and manage run tasks within HCP Terraform. Refer to the Run Tasks Integration API for endpoints to build custom run tasks for the HCP Terraform ecosystem.

Attributes

Run Task Stage Status

The run task stage status is found in data.attributes.status, and you can reference the following list of possible values.

StatusDescription
pendingThe initial status of a run task stage after creation.
runningThe run task stage is executing one or more tasks, which have not yet completed.
passedAll of the run task results in the stage passed.
failedOne more results in the run task stage failed.
awaiting_overrideThe task stage is waiting for user input. Once a user manually overrides the failed run tasks, the run returns to the running state.
erroredThe run task stage has errored.
canceledThe run task stage has been canceled.
unreachableThe run task stage could not be executed.

Run Task Result Status

The run task result status is found in data.attributes.status, and you can reference the following list of possible values.

StatusDescription
pendingThe initial status of a run task result after creation.
runningThe associated run task is begun execution and has not yet completed.
passedThe associated run task executed and returned a passing result.
failedThe associated run task executed and returned a failed result.
erroredThe associated run task has errored during execution.
canceledThe associated run task execution has been canceled.
unreachableThe associated run task could not be executed.

List the Run Task Stages in a Run

GET /runs/:run_id/task-stages

ParameterDescription
run_idThe run ID to list task stages for.
StatusResponseReason
200Array of JSON API documents (type: "task-stages")Successfully listed task-stages

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/runs/run-XdgtChJuuUwLoSmw/task-stages

Sample Response

{  "data": [    {      "id": "ts-rL5ZsuwfjqfPJcdi",      "type": "task-stages",      "attributes": {        "status": "passed",        "stage": "post_plan",        "status-timestamps": {          "passed-at": "2022-06-08T20:32:12+08:00",          "running-at": "2022-06-08T20:32:11+08:00"        },        "created-at": "2022-06-08T12:31:56.94Z",        "updated-at": "2022-06-08T12:32:12.315Z"      },      "relationships": {        "run": {          "data": {            "id": "run-XdgtChJuuUwLoSmw",            "type": "runs"          }        },        "task-results": {          "data": [            {              "id": "taskrs-EmnmsEDL1jgd1GTP",              "type": "task-results"            }          ]        },        "policy-evaluations":{          "data":[            {              "id":"poleval-iouaha9KLgGWkBRQ",              "type":"policy-evaluations"            }          ]        }      },      "links": {        "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi"      }    }  ]}

Show a Run Task Stage

GET /task-stages/:task_stage_id

ParameterDescription
:task_stage_idThe run task stage ID to get.

This endpoint shows details of a specific task stage.

StatusResponseReason
200JSON API document (type: "task-stages")Success
404JSON API error objectTask stage not found or user not authorized

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi

Sample Response

{  "data": {    "id": "ts-rL5ZsuwfjqfPJcdi",    "type": "task-stages",    "attributes": {      "status": "passed",      "stage": "post_plan",      "status-timestamps": {        "passed-at": "2022-06-08T20:32:12+08:00",        "running-at": "2022-06-08T20:32:11+08:00"      },      "created-at": "2022-06-08T12:31:56.94Z",      "updated-at": "2022-06-08T12:32:12.315Z"    },    "relationships": {      "run": {        "data": {          "id": "run-XdgtChJuuUwLoSmw",          "type": "runs"        }      },      "task-results": {        "data": [          {            "id": "taskrs-EmnmsEDL1jgd1GTP",            "type": "task-results"          }        ]      },      "policy-evaluations":{        "data":[          {            "id":"poleval-iouaha9KLgGWkBRQ",            "type":"policy-evaluations"          }        ]     }    },    "links": {      "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi"    }  }}

Show a Run Task Result

GET /task-results/:task_result_id

ParameterDescription
:task_result_idThe run task result ID to get.

This endpoint shows the details for a specific run task result.

StatusResponseReason
200JSON API document (type: "task-results")Success
404JSON API error objectTask result not found or user not authorized

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/task-results/taskrs-EmnmsEDL1jgd1GZz

Sample Response

{  "data": {    "id": "taskrs-EmnmsEDL1jgd1GZz",    "type": "task-results",    "attributes": {      "message": "No issues found.\nSeverity threshold is set to low.",      "status": "passed",      "status-timestamps": {        "passed-at": "2022-06-08T20:32:12+08:00",        "running-at": "2022-06-08T20:32:11+08:00"      },      "url": "https://external.service/project/task-123abc",      "created-at": "2022-06-08T12:31:56.954Z",      "updated-at": "2022-06-08T12:32:12.27Z",      "task-id": "task-b6MaHZmGopHDtqhn",      "task-name": "example-task",      "task-url": "https://external.service/task-123abc",      "stage": "post_plan",      "is-speculative": false,      "workspace-task-id": "wstask-258juqenQeWb3DZz",      "workspace-task-enforcement-level": "mandatory"    },    "relationships": {      "task-stage": {        "data": {          "id": "ts-rL5ZsuwfjqfPJczZ",          "type": "task-stages"        }      }    },    "links": {      "self": "/api/v2/task-results/taskrs-EmnmsEDL1jgd1GZz"    }  }}

Available Related Resources

Task Stage

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

ResourceDescription
runInformation about the associated run.
run.workspaceInformation about the associated workspace.
task-resultsInformation about the results for a task-stage.
policy-evaluationsInformation about the policy evaluations for a task-stage.

Override a Task Stage

POST /task-stages/:task_stage_id/actions/override

ParameterDescription
:task_stage_idThe ID of the task stage to override.

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi/actions/override

Sample Response

{   "data":{      "id":"ts-F7MumZQcJzVh1ZZk",      "type":"task-stages",      "attributes":{         "status":"running",         "stage":"post_plan",         "status-timestamps":{            "running-at":"2022-09-21T06:36:54+00:00",            "awaiting-override-at":"2022-09-21T06:31:50+00:00"         },         "created-at":"2022-09-21T06:29:44.632Z",         "updated-at":"2022-09-21T06:36:54.952Z",         "permissions":{            "can-override-policy":true,            "can-override-tasks":false,            "can-override":true         },         "actions":{            "is-overridable":false         }      },      "relationships":{         "run":{            "data":{               "id":"run-K6N4BAz8NfUyR2QB",               "type":"runs"            }         },         "task-results":{            "data":[            ]         },         "policy-evaluations":{            "data":[               {                  "id":"poleval-atNKxwvjYy4Gwk3k",                  "type":"policy-evaluations"               }            ]         }      },      "links":{         "self":"/api/v2/task-stages/ts-F7MumZQcJzVh1ZZk"      }   }}
Edit this page on GitHub