This document provides instructions for deleting an Agent to free up agent capacity.
Agents are considered active and count towards the organization’s purchased agent capacity if they are in the
Unknown state. Agents which are in the
Exited state do not count towards the organization’s total agent capacity.
Agents in the
Unknown state continue to be counted against the organization’s total agent allowance, as this status is typically an indicator of a temporary communication issue between the agent and Terraform Cloud.
Unknown agents which do not respond after a period of 2 hours will automatically transition to an
Errored state, at which point they will not count against the agent allowance.
Agents may also have an
Unknown status if they are terminated without exiting gracefully. Agents should always be shut down according to the Stopping the Agent documentation to allow them to deregister from Terraform Cloud. We strongly recommend ensuring that any process supervisor, application scheduler, or other runtime manager is configured to follow this procedure to minimize
Unknown agent statuses.
It is possible to delete the Agent to release the slot it occupies prior to the 2 hour transition window. Note that Agents must have a status of
Exited before being deleted.
Locate the Agent Pool ID that you wish to adjust the status for using the Locate the Agent Pool ID API endpoint.
curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/organizations/$ORGANIZATION/agent-pools
Once the Agent pool ID has been located, use the List the Agents API endpoint to list all Agents under the Agent pool.
curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/agent-pools/$AGENT_POOL_ID/agents
Using the Agent ID gathered from the previous call, use the Delete an Agent API endpoint to delete the agent.
curl \ --header "Authorization: Bearer $TOKEN" \ --request DELETE \ https://app.terraform.io/api/v2/agents/$AGENT_ID
For more information about Terraform Cloud Agents and API endpoints please visit: