Diagnostics API reference

The diagnostics endpoint performs comprehensive health diagnostics of all Terraform Enterprise subsystems. It returns detailed status information for each component, including warnings and errors. You can customize the timeout, filter specific checks, and target specific nodes.

Perform diagnostics

This endpoint runs diagnostic checks on Terraform Enterprise subsystems. Authentication is required to use this endpoint. To generate a token for the endpoint, refer to Generate a system API token in the CLI reference documentation.

GET /api/v1/diagnostics

Query parameters

Parameter	Type	Description
`timeout`	integer	Optional. Diagnostic check timeout in seconds. Valid range is `1`-`300`. Default is `30`. The timeout applies to the entire diagnostic execution, regardless of how many nodes are targeted.
`check`	array of strings	Optional. Filter checks to run by group or specific checks. Format: `{group_name}` or `{group_name.check_name}`. Use commas to separate multiple values in the URL, for example: `?check=redis,database.valid_config`. If omitted, all checks run.
`nodes`	array of strings	Optional. Filter diagnostics to run on specific nodes by node identifier. Repeat the parameter for multiple values in the URL, for example: `?nodes=node-id-1&nodes=node-id-2`. If omitted, diagnostics run on all active nodes. Providing an empty value returns an error. You can combine this parameter with the `check` parameter to run specific checks on specific nodes. Use the `/api/v1/nodes` endpoint to retrieve valid node identifiers.

Sample request

The following example runs all diagnostic checks on all nodes with a custom timeout:

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/diagnostics?timeout=60&check=redis,database"

The following example runs diagnostics on a specific node:

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/diagnostics?nodes=node-id-1"

The following example combines node and check filters to run only the database and redis checks on two specific nodes:

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/diagnostics?nodes=node-id-1&nodes=node-id-2&check=redis,database"

Sample response

[
  {
    "node": "84ebea16aab1",
    "status": "OK",
    "created_at": "2026-02-03T21:26:27.985512712Z",
    "duration": 0.071152,
    "checks": [
      {
        "group": "redis",
        "status": "OK",
        "checks": [
          {
            "name": "connection",
            "status": "OK"
          },
          {
            "name": "config",
            "status": "OK"
          },
          {
            "name": "version",
            "status": "OK"
          },
          {
            "name": "permissions",
            "status": "OK"
          }
        ]
      },
      {
        "group": "database",
        "status": "OK",
        "checks": [
          {
            "name": "connection",
            "status": "OK"
          },
          {
            "name": "version",
            "status": "OK"
          },
          {
            "name": "extensions",
            "status": "OK"
          },
          {
            "name": "user_permissions",
            "status": "OK"
          }
        ]
      }
    ]
  }
]

Response attributes

The endpoint returns an array of diagnostic results with the following attributes. The response includes one array of results per node.

Attribute	Type	Description
`node`	string	Identifier of the node that these diagnostic results belong to
`status`	string	Overall status of the diagnostics for this node: `OK`, `WARNING`, or `ERROR`. If subchecks have different statuses, the `status` is set to the highest severity: `ERROR` takes precedence over `WARNING`, which takes precedence over `OK`.
`created_at`	datetime	When the diagnostics were performed
`duration`	float	Time taken to run diagnostics in seconds
`checks`	array of objects	Detailed results for each check group
`checks[].group`	string	Name of the check group
`checks[].status`	string	Status of the group: `OK`, `WARNING`, or `ERROR`
`checks[].checks`	array of objects	Individual checks within the group
`checks[].checks[].name`	string	Name of the individual check
`checks[].checks[].status`	string	Status of the check: `OK`, `WARNING`, or `ERROR`

Response codes

Status	Response	Reason
200	JSON API document	Diagnostics completed successfully
400	JSON API error object	Invalid request parameters, such as timeout out of range
406	JSON API error object	Only `application/json` is supported
429	JSON API error object	Another diagnostic check is already running
503	JSON API document	One or more checks failed

System API Overview

Terraform Enterprise Only: The System API is exclusive to Terraform Enterprise. It enables access to deployment configuration and data.

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.

Port Configuration

By default, the System API is accessible on HTTPS port 8443. This port can be configured through the TFE_ADMIN_HTTPS_PORT environment variable in your deployment configuration.

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 and is separate from the main Terraform Enterprise API.

For example, if the API endpoint documentation defines the path /ping then the full path is /api/v1/ping.