A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation » Agent Pools and Agents APIAn 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 PoolsGET /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.
» Query ParametersThis 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.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 .
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/organizations/my-organization/agent-pools
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/organizations/my-organization/agent-pools
» Sample Response{
"data" : [
{
"id" : "apool-yoGUFz5zcRMMz53i" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"created-at" : "2020-08-05T18:10:26.964Z" ,
"organization-scoped" : false
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [
{
"id" : "ws-9EEkcEQSA3XgWyGe" ,
"type" : "workspaces"
}
]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 1
} ,
"status-counts" : {
"total" : 1 ,
"matching" : 1
}
}
}
{
"data" : [
{
"id" : "apool-yoGUFz5zcRMMz53i" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"created-at" : "2020-08-05T18:10:26.964Z" ,
"organization-scoped" : false
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [
{
"id" : "ws-9EEkcEQSA3XgWyGe" ,
"type" : "workspaces"
}
]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 1
} ,
"status-counts" : {
"total" : 1 ,
"matching" : 1
}
}
}
» List AgentsGET /agent-pools/:agent_pool_id/agents
Parameter Description :agent_pool_id
The ID of the Agent Pool to list.
» Query ParametersThis 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 Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/agents
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/agents
» Sample Response{
"data" : [
{
"id" : "agent-A726QeosTCpCumAs" ,
"type" : "agents" ,
"attributes" : {
"name" : "my-cool-agent" ,
"status" : "idle" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-10-09T18:52:25.246Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-A726QeosTCpCumAs"
}
} ,
{
"id" : "agent-4cQzjbr1cnM6Pcxr" ,
"type" : "agents" ,
"attributes" : {
"name" : "my-other-cool-agent" ,
"status" : "exited" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-08-12T15:25:09.726Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-4cQzjbr1cnM6Pcxr"
}
} ,
{
"id" : "agent-yEJjXQCucpNxtxd2" ,
"type" : "agents" ,
"attributes" : {
"name" : null ,
"status" : "errored" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-08-11T06:22:20.300Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-yEJjXQCucpNxtxd2"
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 3
}
}
}
{
"data" : [
{
"id" : "agent-A726QeosTCpCumAs" ,
"type" : "agents" ,
"attributes" : {
"name" : "my-cool-agent" ,
"status" : "idle" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-10-09T18:52:25.246Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-A726QeosTCpCumAs"
}
} ,
{
"id" : "agent-4cQzjbr1cnM6Pcxr" ,
"type" : "agents" ,
"attributes" : {
"name" : "my-other-cool-agent" ,
"status" : "exited" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-08-12T15:25:09.726Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-4cQzjbr1cnM6Pcxr"
}
} ,
{
"id" : "agent-yEJjXQCucpNxtxd2" ,
"type" : "agents" ,
"attributes" : {
"name" : null ,
"status" : "errored" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-08-11T06:22:20.300Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-yEJjXQCucpNxtxd2"
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 3
}
}
}
» Show an Agent PoolGET /agent-pools/:id
Parameter Description :id
The ID of the Agent Pool to show
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
» Sample Response{
"data" : {
"id" : "apool-yoGUFz5zcRMMz53i" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"created-at" : "2020-08-05T18:10:26.964Z" ,
"organization-scoped" : false
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [
{
"id" : "ws-9EEkcEQSA3XgWyGe" ,
"type" : "workspaces"
}
]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
{
"data" : {
"id" : "apool-yoGUFz5zcRMMz53i" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"created-at" : "2020-08-05T18:10:26.964Z" ,
"organization-scoped" : false
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [
{
"id" : "ws-9EEkcEQSA3XgWyGe" ,
"type" : "workspaces"
}
]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
» Show an AgentGET /agents/:id
Parameter Description :id
The ID of the agent to show
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
» Sample Response{
"data" : {
"id" : "agent-Zz9PTEcUgBtYzht8" ,
"type" : "agents" ,
"attributes" : {
"name" : "my-agent" ,
"status" : "busy" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-09-08T18:47:35.361Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-Zz9PTEcUgBtYzht8"
}
}
}
{
"data" : {
"id" : "agent-Zz9PTEcUgBtYzht8" ,
"type" : "agents" ,
"attributes" : {
"name" : "my-agent" ,
"status" : "busy" ,
"ip-address" : "123.123.123.123" ,
"last-ping-at" : "2020-09-08T18:47:35.361Z"
} ,
"links" : {
"self" : "/api/v2/agents/agent-Zz9PTEcUgBtYzht8"
}
}
}
» Delete an AgentDELETE /agents/:id
Parameter Description :id
The ID of the agent to delete
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--request DELETE \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
curl \
--header "Authorization: Bearer $TOKEN " \
--request DELETE \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
» Create an Agent PoolPOST /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.
» Request BodyThis 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. data.relationships.allowed-workspaces.data.type
string Must be "workspaces"
. data.relationships.allowed-workspaces.data.id
string The ID of the workspace that has permission to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces .
» Sample Payload{
"data" : {
"type" : "agent-pools" ,
"attributes" : {
"name" : "my-pool" ,
"organization-scoped" : false ,
} ,
"relationships" : {
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
}
}
}
{
"data" : {
"type" : "agent-pools" ,
"attributes" : {
"name" : "my-pool" ,
"organization-scoped" : false ,
} ,
"relationships" : {
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
}
}
}
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/organizations/my-organization/agent-pools
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/organizations/my-organization/agent-pools
» Sample Response{
"data" : {
"id" : "apool-55jZekR57npjHHYQ" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "my-pool" ,
"created-at" : "2020-10-13T16:32:45.165Z" ,
"organization-scoped" : false ,
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [ ]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-55jZekR57npjHHYQ"
}
}
}
{
"data" : {
"id" : "apool-55jZekR57npjHHYQ" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "my-pool" ,
"created-at" : "2020-10-13T16:32:45.165Z" ,
"organization-scoped" : false ,
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [ ]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-55jZekR57npjHHYQ"
}
}
}
» Update an Agent PoolPATCH /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 BodyThis 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. data.relationships.allowed-workspaces.data.type
string Must be "workspaces"
. data.relationships.allowed-workspaces.data.id
string The ID of the workspace that has permission to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces .
» Sample Payload{
"data" : {
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"organization-scoped" : false ,
} ,
"relationships" : {
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
}
}
}
{
"data" : {
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"organization-scoped" : false ,
} ,
"relationships" : {
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
}
}
}
» Sample Request$ curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
$ curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
» Sample Response{
"data" : {
"id" : "apool-yoGUFz5zcRMMz53i" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"created-at" : "2020-08-05T18:10:26.964Z"
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [
{
"id" : "ws-9EEkcEQSA3XgWyGe" ,
"type" : "workspaces"
}
]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
{
"data" : {
"id" : "apool-yoGUFz5zcRMMz53i" ,
"type" : "agent-pools" ,
"attributes" : {
"name" : "example-pool" ,
"created-at" : "2020-08-05T18:10:26.964Z"
} ,
"relationships" : {
"agents" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
} ,
"authentication-tokens" : {
"links" : {
"related" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
} ,
"workspaces" : {
"data" : [
{
"id" : "ws-9EEkcEQSA3XgWyGe" ,
"type" : "workspaces"
}
]
} ,
"allowed-workspaces" : {
"data" : [
{
"id" : "ws-x9taqV23mxrGcDrn" ,
"type" : "workspaces"
}
]
}
} ,
"links" : {
"self" : "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
» Delete an Agent PoolDELETE /agent-pools/:agent_pool_id
Parameter Description :agent_pool_id
The ID of the agent pool ID to delete
» Sample Request$ curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
$ curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
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.