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. You can configure run tasks during the Pre-Plan Stage and Post-Plan Stage.
Note: Pre-plan run tasks are in beta.
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.
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.
{"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"}}}
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
Additional information about the associated run.
run.workspace
Additional information about the associated workspace.
task-results
Additional information about the results for a task-stage.