Task stages and results API reference

HCP Terraform uses task stages and task results to track workspace 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 tasks associated to the workspace. Each task in the workspace is configured to begin during a specific run stage. HCP Terraform creates a task stage object for each run stage that triggers tasks. You can configure tasks during the Pre-Plan Stage, Post-Plan Stage, Pre-Apply Stage and Post-Apply Stage.

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

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

Attributes

Task Stage Status

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

Task Result Status

The 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 task result after creation.
`running`	The associated task is begun execution and has not yet completed.
`passed`	The associated task executed and returned a passing result.
`failed`	The associated task executed and returned a failed result.
`errored`	The associated task has errored during execution.
`canceled`	The associated task execution has been canceled.
`unreachable`	The associated task could not be executed.

List the 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"
        },
        "duration": 1000,
        "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 Task Stage

GET /task-stages/:task_stage_id

Parameter	Description
`:task_stage_id`	The 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"
      },
      "duration": 1000,
      "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 Task Result

GET /task-results/:task_result_id

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

This endpoint shows the details for a specific 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"
      },
      "duration": 1000,
      "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"
         },
         "duration": 304000,
         "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"
      }
   }
}

Task stages and results API reference

Attributes

Task Stage Status

Task Result Status

List the Task Stages in a Run

Query Parameters

Sample Request

Sample Response

Show a Task Stage

Sample Request

Sample Response

Show a Task Result

Sample Request

Sample Response

Available Related Resources

Task Stage

Override a Task Stage

Sample Request

Sample Response