Type '/' to Search

»Run Task Stages and Results API

Note: Run Tasks is a paid feature, available as part of the Team & Governance upgrade package. Refer to Terraform Cloud pricing for details.

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

When Terraform Cloud 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. Terraform Cloud creates a run task stage object for each run stage that will trigger run tasks. Currently, you can only configure run tasks during the Post-Plan Stage, so Terraform Cloud produces one post-plan run task stage for each run.

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, Terraform Cloud 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 Terraform Cloud. Refer to the Run Tasks Integration API for endpoints to build custom run tasks for the Terraform Cloud 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.
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

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"
            }
          ]
        }
      },
      "links": {
        "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi"
      }
    }
  ]
}

{
  "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"
            }
          ]
        }
      },
      "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

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"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi"
    }
  }
}

{
  "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"
          }
        ]
      }
    },
    "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

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

{
  "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
runAdditional information about the associated run.
run.workspaceAdditional information about the associated workspace.
task-resultsAdditional information about the results for a task-stage.