Agent Pools and Agents API
An Agent Pool represents a group of Agents, often related to one another by sharing a common network segment or purpose. A workspace may be configured to use one of the organization's agent pools to run remote operations with isolated, private, or on-premises infrastructure.
Note: Terraform Cloud Agents are a paid feature, available as part of the Terraform Cloud for Business upgrade package. Learn more about Terraform Cloud pricing here.
List Agent Pools
GET /organizations/:organization_name/agent-pools
Parameter | Description |
---|---|
:organization_name | The name of the organization. |
This endpoint allows you to list agent pools, their agents, and their tokens for an organization.
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agent-pools" ) | Success |
404 | JSON API error object | Organization not found |
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 | |
---|---|---|
q | Optional. A search query string. Agent pools are searchable by name. Available in Terraform Enterprise v202207-1 and later. | |
sort | Optional. Allows sorting the returned agents pools. Valid values are "name" and "created-at" . Prepending a hyphen to the sort parameter will reverse the order (e.g. "-name" ). | |
page[number] | Optional. If omitted, the endpoint will return the first page. | |
page[size] | Optional. If omitted, the endpoint will return 20 agent pools per page. | |
filter[allowed_workspaces][name] | Optional. Filters agent pools to those associated with the given workspace. The workspace must have permission to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces. Available in Terraform Enterprise v202207-1 and later. |
Sample Request
Sample Response
List Agents
GET /agent-pools/:agent_pool_id/agents
Parameter | Description |
---|---|
:agent_pool_id | The ID of the Agent Pool to list. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agents" ) | Success |
404 | JSON API error object | Agent Pool 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[last-ping-since] | Optional. Accepts a date in ISO8601 format (ex. 2020-08-11T10:41:23Z ). |
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 agents per page. |
Sample Request
Sample Response
Show an Agent Pool
GET /agent-pools/:id
Parameter | Description |
---|---|
:id | The ID of the Agent Pool to show |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agent-pools" ) | Success |
404 | JSON API error object | Agent Pool not found, or user unauthorized to perform action |
Sample Request
Sample Response
Show an Agent
GET /agents/:id
Parameter | Description |
---|---|
:id | The ID of the agent to show |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agents" ) | Success |
404 | JSON API error object | Agent not found, or user unauthorized to perform action |
Sample Request
Sample Response
Delete an Agent
DELETE /agents/:id
Parameter | Description |
---|---|
:id | The ID of the agent to delete |
Status | Response | Reason |
---|---|---|
204 | Nothing | Success |
412 | JSON API error object | Agent is not deletable. Agents must have a status of unknown , errored , or exited before being deleted. |
404 | JSON API error object | Agent not found, or user unauthorized to perform action |
Sample Request
Create an Agent Pool
POST /organizations/:organization_name/agent-pools
Parameter | Description |
---|---|
:organization_name | The name of the organization. |
This endpoint allows you to create an Agent Pool for an organization. Only one Agent Pool may exist for an organization.
Status | Response | Reason |
---|---|---|
201 | JSON API document (type: "agent-pools" ) | Agent Pool successfully created |
404 | JSON API error object | Organization not found or user unauthorized to perform action |
422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "agent-pools" . | |
data.attributes.name | string | The name of the agent pool, which can only include letters, numbers, - , and _ . This will be used as an identifier and must be unique in the organization. | |
data.attributes.organization-scoped | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. Available in Terraform Enterprise v202207-1 and later. |
data.relationships.allowed-workspaces.data.type | string | Must be "workspaces" . Available in Terraform Enterprise v202207-1 and later. | |
data.relationships.allowed-workspaces.data.id | string | The ID of the workspace that is allowed to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces. Available in Terraform Enterprise v202207-1 and later. |
Sample Payload
Sample Request
Sample Response
Update an Agent Pool
PATCH /agent-pools/:id
Parameter | Description |
---|---|
:id | The ID of the Agent Pool to update |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agent-pools" ) | Success |
404 | JSON API error object | Agent Pool not found, or user unauthorized to perform action |
422 | JSON error document | Malformed request body (missing attributes, wrong types, etc.) |
Request Body
This PATCH endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "agent-pools" . | |
data.attributes.name | string | (previous value) | The name of the agent pool, which can only include letters, numbers, - , and _ . This will be used as an identifier and must be unique in the organization. |
data.attributes.organization-scoped | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. Available in Terraform Enterprise v202207-1 and later. |
data.relationships.allowed-workspaces.data.type | string | Must be "workspaces" . Available in Terraform Enterprise v202207-1 and later. | |
data.relationships.allowed-workspaces.data.id | string | The ID of the workspace that is allowed to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces. Available in Terraform Enterprise v202207-1 and later. |
Sample Payload
Sample Request
Sample Response
Delete an Agent Pool
DELETE /agent-pools/:agent_pool_id
Parameter | Description |
---|---|
:agent_pool_id | The ID of the agent pool ID to delete |
Sample Request
Available Related Resources
The GET endpoints above can optionally return related resources, if requested with the include
query parameter. The following resource types are available:
Resource Name | Description |
---|---|
workspaces | The workspaces attached to this agent pool. |