#ActionRuns

---

#GET /{o}/{p}/action-runs

List action runs

List action runs in this project with optional filtering and pagination.

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Query parameters

Name	Type	Description
actionName	string	Filter by action name
entityId	string(uuid)	Filter by entity ID
status	pending | running | succeeded | failed | cancelled | dispatching | blocked	Filter by status
limit	integer	Max results (1-2000)
cursor	string	Keyset cursor from the previous page

Responses

Status	Description	Schema
200	OK	ActionRunPage
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/action-runs/{id}

Get an action run by id

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string
id	string

Responses

Status	Description	Schema
200	OK	ActionRun
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#DELETE /{o}/{p}/action-runs/{id}

Cancel a pending action run

Auth: Bearer token required · Permission: actions:cancel

Path parameters

Name	Type	Description
o	string
p	string
id	string

Responses

Status	Description	Schema
200	OK	ActionRun
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
409	Conflict	Error

---

#POST /{o}/{p}/action-runs/{id}/callback

Complete an action run (external workflow callback)

Called by the external workflow to report success/failure. Takes TWO credentials in two headers: a project token or session carrying at least data:read in Authorization: Bearer, and the per-run HMAC-signed callback token in X-Terrantula-Callback-Token. The HMAC is what actually authorizes completing this specific run; the RBAC permission is a floor on the bearer, not the credential doing the authorizing. The two are separate headers because they are separate credentials — carrying both on Authorization made the pair unsatisfiable and the endpoint unreachable (#390).

Write-verb route on a :read permission because the per-run HMAC callback token (verifyCallbackToken), not this permission, authorizes completing this specific run. data:read is the deliberate floor for the bearer project token — a read-capable token is still required alongside the HMAC, never neither — kept below the write-tier permissions so external workflows need only read access, not the ability to trigger or cancel runs. #260. The two credentials travel in two headers: the bearer in Authorization, the HMAC in X-Terrantula-Callback-Token, because one header cannot carry both and while it tried to, the pair was unsatisfiable (#390).

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string
id	string

Request body (application/json)

Type: object | object

Responses

Status	Description	Schema
200	OK	ActionRun
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
409	Conflict	Error

#Schemas

#ActionRun

Field	Type	Description
id	string(uuid)	(required)
actionName	string	(required)
entityId	string(uuid) | null	(required)
status	pending | running | succeeded | failed | cancelled | dispatching | blocked	(required)
parameters	object	(required)
recommendations	object	(required)
triggeredBy	string	(required)
createdAt	string | string	(required)
startedAt	string | string | null	(required)
completedAt	string | string | null	(required)
error	string | null	(required)
output	object | null	(required)
orgId	string	(required)
projectId	string	(required)
operationEntityId	string | null	(required)
metadata	object | null	(required)
resolvedTargets	object	(required)

#ActionRunListRow

Field	Type	Description
id	string(uuid)	(required)
actionName	string	(required)
entityId	string(uuid) | null	(required)
status	pending | running | succeeded | failed | cancelled | dispatching | blocked	(required)
parameters	object	(required)
recommendations	object	(required)
triggeredBy	string	(required)
createdAt	string | string	(required)
startedAt	string | string | null	(required)
completedAt	string | string | null	(required)
error	string | null	(required)
output	object | null	(required)
orgId	string	(required)
projectId	string	(required)
operationEntityId	string | null	(required)
metadata	object | null	(required)
resolvedTargets	object	(required)
entityName	string | null	(required)
operationEntityName	string | null	(required)

#ActionRunPage

Field	Type	Description
items	ActionRunListRow[]	(required)
nextCursor	string | null	Cursor for the next page; null on the final page (required)

#Error

Field	Type	Description
error	string	(required)
code	string

#PlacementDecision

Field	Type	Description
groupingKind	Cell | DeploymentTargetSet	(required)
group	string	(required)
policy	least-loaded | round-robin | random	(required)
metric	string | null	(required)
metricValue	number | null	(required)
candidates	integer	(required)

#ResolvedTargetRecord

Field	Type	Description
name	string	(required)
provider	aws | gcp | s3-backend | tfc-workspace | generic	(required)
placement	PlacementDecision