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: HCP Terraform Free edition includes one self-hosted agent. Refer to HCP Terraform pricing for details.
GET /organizations/:organization_name/agent-pools
: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.
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. filter[allowed_projects][name] Optional. Filters agent pools to those associated with the given project. The project must have permission to use the agent pool. Refer to Scoping Agent Pools to Specific Projects. Response fields
Responses for this endpoint can contain an attributes object with the following fields:
data.attributes.agent-count number The number of agents in Idle, Busy or Unknown states. Agents that are Exited or Errored are excluded. data.attributes.meta.status-counts.total number The total number of resources the filter was applied to. data.attributes.meta.status-counts.matching number The total number of resources returned, which match the filter you applied. Sample Request
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
{
"data": [
{
"id": "apool-yoGUFz5zcRMMz53i",
"type": "agent-pools",
"attributes": {
"name": "example-pool",
"created-at": "2020-08-05T18:10:26.964Z",
"organization-scoped": false,
"agent-count": 3
},
"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"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"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
}
}
}
GET /agent-pools/:agent_pool_id/agents
:agent_pool_id The ID of the Agent Pool to list. 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.
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
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
{
"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
}
}
}
GET /agent-pools/:id
:id The ID of the Agent Pool to show Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
{
"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"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"links": {
"self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
GET /agents/:id
:id The ID of the agent to show Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
{
"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"
}
}
}
This endpoint lists details about an agent along with that agent's status. Learn more about agents statuses.
DELETE /agents/:id
:id The ID of the agent to delete Status Response Reason 204 No Content 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
curl \
--header "Authorization: Bearer $TOKEN" \
--request DELETE \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
POST /organizations/:organization_name/agent-pools
: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 Descriptiondata.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. data.relationships.allowed-projects.data.type string Must be "projects". Refer to Scoping Agent Pools to Specific Projects. data.relationships.allowed-projects.data.id string The ID of the project that has permission to use the agent pool. data.relationships.excluded-workspaces.data.type string Must be "workspaces". data.relationships.excluded-workspaces.data.id string The ID of the workspace that is excluded from the scope of the agent pool. Sample Payload
{
"data": {
"type": "agent-pools",
"attributes": {
"name": "my-pool",
"organization-scoped": false
},
"relationships": {
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
}
}
}
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
{
"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"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"links": {
"self": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ"
}
}
}
PATCH /agent-pools/:id
: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 Descriptiondata.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. data.relationships.allowed-projects.data.type string Must be "projects". Refer to Scoping Agent Pools to Specific Projects. data.relationships.allowed-projects.data.id string The ID of the project that has permission to use the agent pool. data.relationships.excluded-workspaces.data.type string Must be "workspaces". data.relationships.excluded-workspaces.data.id string The ID of the workspace that is excluded from the scope of the agent pool. Sample Payload
{
"data": {
"type": "agent-pools",
"attributes": {
"name": "example-pool",
"organization-scoped": false
},
"relationships": {
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
}
}
}
$ 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
{
"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"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"links": {
"self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
DELETE /agent-pools/:agent_pool_id
: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
The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:
workspaces The workspaces attached to this agent pool.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4