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.

Status	Description
`pending`	The initial status of a run task stage after creation.
`running`	The run task stage is executing one or more tasks, which have not yet completed.
`passed`	All of the run task results in the stage passed.
`failed`	One more results in the run task stage failed.
`awaiting_override`	The task stage is waiting for user input. Once a user manually overrides the failed run tasks, the run returns to the `running` state.
`errored`	The run task stage has errored.
`canceled`	The run task stage has been canceled.
`unreachable`	The 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.

Status	Description
`pending`	The initial status of a run task result after creation.
`running`	The associated run task is begun execution and has not yet completed.
`passed`	The associated run task executed and returned a passing result.
`failed`	The associated run task executed and returned a failed result.
`errored`	The associated run task has errored during execution.
`canceled`	The associated run task execution has been canceled.
`unreachable`	The associated run task could not be executed.

List the Run Task Stages in a Run

GET /runs/:run_id/task-stages

Parameter	Description
`run_id`	The run ID to list task stages for.

Status	Response	Reason
200	Array 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.

Parameter	Description
`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

Parameter	Description
`:task_stage_id`	The run task stage ID to get.

This endpoint shows details of a specific task stage.

Status	Response	Reason
200	JSON API document (`type: "task-stages"`)	Success
404	JSON API error object	Task 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

Parameter	Description
`:task_result_id`	The run task result ID to get.

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

Status	Response	Reason
200	JSON API document (`type: "task-results"`)	Success
404	JSON API error object	Task 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"
    }
  }
}

Task Stage

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

Resource	Description
`run`	Information about the associated run.
`run.workspace`	Information about the associated workspace.
`task-results`	Information about the results for a task-stage.
`policy-evaluations`	Information about the policy evaluations for a task-stage.

Override a Task Stage

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

Parameter	Description
`:task_stage_id`	The 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"
      }
   }
}

Run task stages and results API reference

Attributes

Run Task Stage Status

Run Task Result Status

List the Run Task Stages in a Run

Query Parameters

Sample Request

Sample Response

Show a Run Task Stage

Sample Request

Sample Response

Show a Run Task Result

Sample Request

Sample Response

Available Related Resources

Task Stage

Override a Task Stage

Sample Request

Sample Response