/usage/bundle endpoint reference

This endpoint provides a usage bundle. For more information about the product usage data structure and the specific metrics that Terraform Enterprise collects, refer to the Terraform Enterprise usage data reference.

GET /api/v1/usage/bundle

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  https://tfe.example.com:8443/api/v1/usage/bundle

Sample Response

{
    "version": "2",
    "mode": "automatic",
    "timestamp": "2025-06-05T19:54:16.016366464Z",
    "signature": "fdd077fa855d11aa855d11a855d11aa855d11a",
    "checksum": 5193303679122559012,
    "snapshots": [
        {
            "snapshot_version": 2,
            "id": "0001XXXXXXGXXXRMXXXXXXXXXXXX",
            "timestamp": "2025-04-10T00:00:04.386332246Z",
            "schema_version": "2.0.0",
            "product": "terraform",
            "process_id": "0001XXXXXXGXXXRMXXXXXXXXXXXX",
            "metrics": {
                "workspacecount": {
                    "key": "workspacecount",
                    "value": 0,
                    "mode": "write"
                }
            },
            "product_version": "v202504-1",
            "license_id": "b855d11a-2b6e-4b0c-8e3f-2a3e5d6b7f9c",
            "checksum": 5193303679122559012,
            "metadata": {}
        }
    ]
}

Response Codes

Status	Response	Reason
200	JSON usage bundle	Successfully retrieved usage data
403	JSON API error object	Not authorized to access this endpoint
429	JSON API error object	Too many requests
500	JSON API error object	Internal server error

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.

Network and port configuration

Access to the System API depends on the TFE_ADMIN_CONSOLE_ACCESS_MODE setting:

Access mode	Port	Base path	Example (`/ping`)
`port` (default)	Dedicated admin port (configured by `TFE_ADMIN_HTTPS_PORT`, defaults to `8443`)	`/api/v1`	`https://<TFE_HOSTNAME>:8443/api/v1/ping`
`path`	Standard HTTPS port (configured by `TFE_HTTPS_PORT`, defaults to `443`)	`/platform/admin/api/v1`	`https://<TFE_HOSTNAME>/platform/admin/api/v1/ping`
`both`	Either dedicated admin port or standard HTTPS port	`/api/v1` (port) or `/platform/admin/api/v1` (path)	Accessible via both endpoints

Important: When TFE_ADMIN_CONSOLE_ACCESS_MODE is set to path, Terraform Enterprise does not expose System API routes through the dedicated admin port. You must send System API requests over standard HTTPS using the /platform/admin/api/v1 prefix.

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.

Enable automated product usage reports - Instructions for configuring Terraform Enterprise to automatically send product usage data to HashiCorp
Generate product usage report using the CLI - Instructions for generating product usage reports manually