Node drain status API reference

The node drain status endpoints report whether a Terraform Enterprise node is actively running Terraform tasks and whether it is safe to terminate.

Node status values

Endpoints report one of the following status values for each node.

Get local node drain status

This endpoint returns the drain status of the individual node that receives the request. Because this endpoint targets the local node, send the request directly to that node instead of through a load balancer. Authentication is required to use this endpoint.

GET /api/v1/nodes/self/drain-status

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/nodes/self/drain-status"

Sample response

The following response shows a node that has finished draining and is safe to terminate. Because the drain is complete, status is standby, is_safe_to_terminate is true, active_tasks is empty, both drain_started_at and force_terminate_at are populated, and force_terminate_at is exactly drain_started_at plus 24 hours.

{
  "hostname": "tfe-1",
  "status": "standby",
  "is_safe_to_terminate": true,
  "active_tasks_count": 0,
  "active_tasks": [],
  "drain_started_at": "2026-06-09T14:32:00Z",
  "force_terminate_at": "2026-06-10T14:32:00Z"
}

When the drain status cannot be determined, status is error, active_tasks_count is null, and active_tasks is empty. The request still returns 200.

{
  "hostname": "tfe-1",
  "status": "error",
  "is_safe_to_terminate": false,
  "active_tasks_count": null,
  "active_tasks": []
}

Response codes

Get cluster drain status

This endpoint returns a collection with the drain status of every node in the Terraform Enterprise deployment, sorted by hostname. It fans the drain status check out to all live nodes and returns one resource per node, so you do not need to query each node individually. A node that cannot be reached still appears in the collection with status: error, and the request stays 200. Use the filter[nodes] parameter to scope the collection to specific nodes by hostname. Authentication is required to use this endpoint.

GET /api/v1/nodes/drain-status

Query parameters

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/nodes/drain-status?filter[nodes]=tfe-1"

Sample response

The following response includes one node. The node tfe-1 is draining and reports one active agent-run task. Each resource's links.self is a relative path that scopes the collection to that node.

{
  "data": [
    {
      "id": "tfe-1",
      "type": "node-drain-status",
      "attributes": {
        "hostname": "tfe-1",
        "status": "draining",
        "is_safe_to_terminate": false,
        "active_tasks_count": 1,
        "active_tasks": [
          {
            "name": "agent-run",
            "started_at": "2026-06-09T14:40:11Z",
            "metadata": {
              "run_id": "run-CkszD4iCEaxnYMkh",
              "workload_id": "plan-pJ5bfP4pFxQVHDkT",
              "workload_type": "Plan",
              "workspace_name": "my-app-prod",
              "organization_name": "acme-corp",
              "organization_id": "org-bright-raven-404724",
              "image_tag": "1.28.8",
              "tfc_address": "https://tfe.example.com",
              "terraform_download_url": "https://releases.hashicorp.com/terraform/1.9.5/terraform_1.9.5_linux_amd64.zip",
              "terraform_checksum": "9f3ca38a6d2a6b1c0f4e3d2c1b0a9988776655443322110aabbccddeeff0011"
            }
          }
        ],
        "drain_started_at": "2026-06-09T14:32:00Z",
        "force_terminate_at": "2026-06-10T14:32:00Z"
      },
      "links": {
        "self": "/api/v1/nodes/drain-status?filter[nodes]=tfe-1"
      }
    }
  ],
  "meta": {
    "partial": false
  }
}

Collection meta block

The top-level document contains a data array and a meta block. The meta block reports whether the snapshot is complete.

Response codes

Response schema

The endpoints describe each node with the same fields. The local endpoint returns these fields at the top level of a flat JSON object, and the cluster endpoint nests them under attributes in each node-drain-status resource.

Per-task fields

Each element of active_tasks describes one task that is currently executing on the node. The task-level name and started_at fields are at the top level of the task object, and the remaining fields are nested under the metadata object. Terraform Enterprise omits any metadata field that has no value, and it never includes sensitive fields such as tokens.

System API Overview

This API is distinct from the regular Admin API and the Backup and Restore API, with its own authentication mechanism.

Authentication

All system API endpoints require authentication with a bearer token generated using the tfectl admin api-token generate command. For more information on token creation and management, refer to the tfectl documentation.

Use the HTTP Header Authorization with the value Bearer <token>.

Rate Limiting

All System API endpoints are rate limited to 1 request per second per authentication token.

Network and port configuration

Access to the System API depends on the TFE_ADMIN_CONSOLE_ACCESS_MODE setting:

Refer to Network settings in the configuration reference for more information about network configuration.

Versioning

The System API is versioned under the /api/v1 prefix (or /platform/admin/api/v1 when using path mode) and is separate from the main Terraform Enterprise API.

For example, if the API endpoint documentation defines the path /ping, the full endpoint path is /api/v1/ping on the dedicated admin port, or /platform/admin/api/v1/ping when using path or both access mode.