Terraform actions API reference

Terraform actions are provider-defined operations that HCP Terraform can invoke during runs. Use these endpoints to list the actions available in a workspace and review action invocations after a run. Refer to Terraform actions for more information about defining actions in providers.

List Actions in a Workspace

GET /workspaces/:workspace_id/terraform-actions

Parameter	Description
`:workspace_id`	The ID of the workspace to list actions from. Obtain this from the workspace settings or the show workspace endpoint.

Status	Response	Reason
200	JSON API document (`type: "actions"`)	Request was successful.
404	JSON API error object	Workspace not found or user unauthorized to perform action.

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
`filter[provider]`	Optional. Return only actions from the specified provider.
`filter[module_address]`	Optional. Return only actions belonging to the specified module. Use `system:root_module` for root module actions, or a module address such as `module.foo.module.bar` for nested child module actions.
`filter[last_invocation][invoked_at][gte]`	Optional. Return actions whose last invocation was invoked at or after this timestamp.
`filter[last_invocation][invoked_at][gt]`	Optional. Return actions whose last invocation was invoked after this timestamp.
`filter[last_invocation][invoked_at][lte]`	Optional. Return actions whose last invocation was invoked at or before this timestamp.
`filter[last_invocation][invoked_at][lt]`	Optional. Return actions whose last invocation was invoked before this timestamp.
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns the default page size.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/terraform-actions?page%5Bsize%5D=20"

Sample Response

{
  "data": [
    {
      "id": "action-ryh1uSaExmQqK72V",
      "type": "actions",
      "attributes": {
        "address": "action.terraform_data.restart",
        "module-address": "module.foo",
        "provider": "terraform",
        "documentation-url": null,
        "created-at": "2026-05-12T15:30:00Z",
        "updated-at": "2026-05-12T15:31:00Z",
        "instance-type": "for_each",
        "count-value": null,
        "for-each-values": ["key1", "key2", "key3"]
      },
      "relationships": {
        "workspace": {
          "data": {
            "id": "ws-4j8p6jX1w33MiDC7",
            "type": "workspaces"
          }
        },
        "last-invocation": {
          "data": {
            "id": "ai-TmqZCTY8bCi6b3Am",
            "type": "action-invocations"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/terraform-actions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/terraform-actions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/terraform-actions?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

GET /workspaces/:workspace_id/terraform-actions/filter-options

This endpoint returns the dynamic filter values available for a workspace's Terraform actions list.

Parameter	Description
`:workspace_id`	The ID of the workspace to retrieve filter options from. Obtain this from the workspace settings or the show workspace endpoint.

Status	Response	Reason
200	JSON API document (`type: "action-filter-options"`)	Request was successful.
404	JSON API error object	Workspace not found or user unauthorized to perform action.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/terraform-actions/filter-options

Sample Response

{
  "data": {
    "id": "ws-4j8p6jX1w33MiDC7",
    "type": "action-filter-options",
    "attributes": {
      "providers": [
        "terraform"
      ]
    }
  }
}

Show an Action

GET /terraform-actions/:action_id

Parameter	Description
`:action_id`	The ID of the action.

Status	Response	Reason
200	JSON API document (`type: "actions"`)	Request was successful.
404	JSON API error object	Action not found or user unauthorized to perform action.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/terraform-actions/action-ryh1uSaExmQqK72V

Sample Response

{
  "data": {
    "id": "action-ryh1uSaExmQqK72V",
    "type": "actions",
      "attributes": {
        "address": "action.terraform_data.restart",
        "module-address": "system:root_module",
        "provider": "terraform",
        "documentation-url": null,
        "created-at": "2026-05-12T15:30:00Z",
        "updated-at": "2026-05-12T15:31:00Z",
        "invocation-count": 3,
        "instance-type": "count",
        "count-value": 3,
        "for-each-values": null
      },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-4j8p6jX1w33MiDC7",
          "type": "workspaces"
        }
      },
      "last-invocation": {
        "data": {
          "id": "ai-TmqZCTY8bCi6b3Am",
          "type": "action-invocations"
        }
      }
    }
  }
}

List Action Invocations Aggregated by Run

GET /terraform-actions/:action_id/invocations/run-summary

This endpoint lists invocations for an action grouped and aggregated by run.

Parameter	Description
`:action_id`	The ID of the action.

Status	Response	Reason
200	JSON API document (`type: "action-invocation-run-summary"`)	Request was successful.
404	JSON API error object	Action not found or user unauthorized to perform action.

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
`filter[run][id]`	Optional. Return run summaries only for the specified run ID.
`filter[invocation_method]`	Optional. Return run summaries for one or more comma-separated invocation methods. Valid values are `direct` and `lifecycle`.
`filter[aggregate_invocation_status]`	Optional. Return run summaries for one or more comma-separated aggregate statuses. Valid values are `successful`, `not_successful`, `not_invoked`, and `run_in_progress`.
`filter[invoked_by]`	Optional. Return run summaries for one or more comma-separated invoker values. Use the action invocation filter options endpoint to discover values.
`filter[source]`	Optional. Return run summaries for one or more comma-separated run sources. Valid values are `tfe-api`, `terraform`, `terraform+cloud`, `tfe-configuration-version`, `tfe-run-trigger`, and `tfe-ui`.
`filter[invoked_at][gte]`	Optional. Return run summaries whose last invocation was invoked at or after this timestamp.
`filter[invoked_at][gt]`	Optional. Return run summaries whose last invocation was invoked after this timestamp.
`filter[invoked_at][lte]`	Optional. Return run summaries whose last invocation was invoked at or before this timestamp.
`filter[invoked_at][lt]`	Optional. Return run summaries whose last invocation was invoked before this timestamp.
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns the default page size.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/terraform-actions/action-ryh1uSaExmQqK72V/invocations/run-summary?filter%5Binvocation_method%5D=direct&page%5Bsize%5D=20"

Sample Response

{
  "data": [
    {
      "id": "action-ryh1uSaExmQqK72V:run-KTuq99JSzgmDSvYj",
      "type": "action-invocation-run-summary",
      "attributes": {
        "aggregate-invocation-status": "successful",
        "invocation-method": "direct",
        "invoked-at": "2026-05-12T15:40:00Z",
        "invoked-by": {
          "username": "example-user",
          "avatar-url": "https://example.com/avatar.png"
        },
        "invocation-statuses": {
          "successful": 1,
          "failed": 0
        },
        "planned-invocation-count": 1
      },
      "relationships": {
        "action": {
          "data": {
            "id": "action-ryh1uSaExmQqK72V",
            "type": "actions"
          }
        },
        "run": {
          "data": {
            "id": "run-KTuq99JSzgmDSvYj",
            "type": "runs"
          }
        }
      }
    }
  ]
}

GET /terraform-actions/:action_id/invocations/filter-options

This endpoint returns dynamic filter values available for an action's invocations list. The response can include system:not_a_user in invoked-by, which represents invocations without a human actor.

Parameter	Description
`:action_id`	The ID of the action.

Status	Response	Reason
200	JSON API document (`type: "action-invocation-filter-options"`)	Request was successful.
404	JSON API error object	Action not found or user unauthorized to perform action.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/terraform-actions/action-ryh1uSaExmQqK72V/invocations/filter-options

Sample Response

{
  "data": {
    "id": "action-ryh1uSaExmQqK72V",
    "type": "action-invocation-filter-options",
    "attributes": {
      "invoked-by": [
        "example-user",
        "system:not_a_user"
      ]
    }
  }
}

List Action Invocations for a Run

GET /terraform-actions/:action_id/runs/:run_id/invocations

This endpoint lists individual invocations for a specific action and run ordered by execution order.

Parameter	Description
`:action_id`	The ID of the action.
`:run_id`	The ID of the run.

Status	Response	Reason
200	JSON API document (`type: "action-invocations"`)	Request was successful.
400	JSON API error object	Invalid request parameter.
404	JSON API error object	Action or run not found, or user unauthorized to perform action.

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
`filter[status]`	Optional. Return invocations for one or more comma-separated final statuses. Valid values are `failed`, `not_invoked`, and `successful`.
`q`	Optional. Search action invocations by key, status, trigger event, or triggering resource address.
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns the default page size.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/terraform-actions/action-ryh1uSaExmQqK72V/runs/run-KTuq99JSzgmDSvYj/invocations?filter%5Bstatus%5D=successful&page%5Bsize%5D=20"

Sample Response

{
  "data": [
    {
      "id": "ai-TmqZCTY8bCi6b3Am",
      "type": "action-invocations",
      "attributes": {
        "final-status": "successful",
        "invocation-method": "direct",
        "action-key": null,
        "action-trigger-event": null,
        "triggering-resource-address": null,
        "action-trigger-block-index": null,
        "actions-list-index": 0,
        "invoked-at": "2026-05-12T15:40:00Z",
        "created-at": "2026-05-12T15:40:00Z",
        "updated-at": "2026-05-12T15:41:00Z"
      },
      "relationships": {
        "action": {
          "data": {
            "id": "action-ryh1uSaExmQqK72V",
            "type": "actions"
          }
        },
        "run": {
          "data": {
            "id": "run-KTuq99JSzgmDSvYj",
            "type": "runs"
          }
        }
      }
    }
  ],
  "meta": {
    "counts": {
      "invocations": {
        "total": 1
      }
    }
  }
}

List Lifecycle Action Invocation Resource Groups

GET /terraform-actions/:action_id/runs/:run_id/invocations/lifecycle-resource-groups

This endpoint lists lifecycle action invocations for a specific action and run. The response is grouped by triggering resource address. The endpoint paginates by resource group, not by individual invocation.

Parameter	Description
`:action_id`	The ID of the action.
`:run_id`	The ID of the run.

Status	Response	Reason
200	JSON API document (`type: "action-invocation-resource-groups"`)	Request was successful.
400	JSON API error object	Invalid request parameter.
404	JSON API error object	Action or run not found, or user unauthorized to perform action.

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
`filter[aggregate_status]`	Optional. Return resource groups for one or more comma-separated aggregate statuses. Valid values are `successful`, `not_invoked`, and `not_successful`.
`q`	Optional. Search resource groups by key, status, aggregate status, trigger event, or triggering resource address.
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns the default page size.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/terraform-actions/action-ryh1uSaExmQqK72V/runs/run-KTuq99JSzgmDSvYj/invocations/lifecycle-resource-groups?filter%5Baggregate_status%5D=successful&page%5Bsize%5D=20"

Sample Response

{
  "data": [
    {
      "id": "aws_instance.example",
      "type": "action-invocation-resource-groups",
      "attributes": {
        "triggering-resource-address": "aws_instance.example",
        "aggregate-invocation-status": "successful",
        "invocations": [
          {
            "id": "ai-zL1x3WQdtgP5ZB8r",
            "final-status": "successful",
            "action-key": null,
            "action-trigger-event": "AfterCreate"
          }
        ]
      }
    }
  ],
  "meta": {
    "counts": {
      "invocations": {
        "total": 1
      },
      "resource-groups": {
        "total": 1
      }
    }
  }
}

Terraform actions API reference

List Actions in a Workspace

Query Parameters

Sample Request

Sample Response

Get Action Filter Options

Sample Request

Sample Response

Show an Action

Sample Request

Sample Response

List Action Invocations Aggregated by Run

Query Parameters

Sample Request

Sample Response

Get Action Invocation Filter Options

Sample Request

Sample Response

List Action Invocations for a Run

Query Parameters

Sample Request

Sample Response

List Lifecycle Action Invocation Resource Groups

Query Parameters

Sample Request

Sample Response