How to list workspaces in an organization using filter and sort query parameters

Introduction

This article provides instructions on how to list all workspaces in a HCP Terraform or Terraform Enterprise organization using the API. You can use query parameters to paginate, filter, and sort the results, which is useful for automation, reporting, or administrative tasks.

Expected Outcome

After following this guide, you will be able to use an API call to retrieve a complete, sorted, and filtered list of workspaces from your organization.

Prerequisites

Before you begin, ensure you have the following:

• An active HCP Terraform or Terraform Enterprise account.
• An API token with appropriate permissions. You can generate a personal API token from your user settings.
• An HTTP client tool such as curl, Postman, or an HTTP library in your preferred programming language.

Procedure

Follow these steps to list, filter, and sort workspaces using the API.

1. Create an API Token

First, generate an API token for authentication.

1. Log into your HCP Terraform or Terraform Enterprise account.
2. Navigate to User Settings by clicking your profile picture in the top-right corner.
3. In the API tokens section, click Create an API token.
4. Copy the generated token and store it securely.

2. List Workspaces

Use the following API call to list workspaces in your organization. This example uses pagination to retrieve the first page with 10 results.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://<TFE_HOSTNAME>/api/v2/organizations/<ORG_NAME>/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=10"

• Replace <TFE_HOSTNAME> with your Terraform Enterprise hostname (e.g., app.terraform.io for HCP Terraform).
• Replace <ORG_NAME> with the name of your organization.
• Set the $TOKEN environment variable to your API token.
• Adjust the page[number] and page[size] parameters as needed.

Note: The API request URL must be properly percent-encoded. For example, [ becomes %5B  and ] becomes %5D .

3. Review Example Response

A successful request returns a JSON object containing a list of workspaces. The following is a truncated example of a single workspace object.

{
  "id": "ws-sPXu2fHeiggxy615",
  "type": "workspaces",
  "attributes": {
    "name": "test1",
    "environment": "default",
    "locked": false,
    "created-at": "2024-10-21T07:44:41.926Z",
    "latest-change-at": "2024-10-21T07:44:41.926Z",
    "terraform-version": "1.9.2",
    "execution-mode": "remote"
  },
  "relationships": {
    "organization": {
      "data": {
        "id": "support",
        "type": "organizations"
      }
    },
    "project": {
      "data": {
        "id": "prj-UwWEsUigxVeqsxKh",
        "type": "projects"
      }
    }
  }
}

4. Filter and Sort Workspaces

You can add a sort parameter to order the results by a specific attribute. This example sorts workspaces by the latest-change-at attribute and uses jq to format the output to show the workspace ID, last change time, and name.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://<TFE_HOSTNAME>/api/v2/organizations/<ORG_NAME>/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=latest-change-at" | \
  jq -r '.data[] | "\(.id) \(.attributes."latest-change-at") \(.attributes.name)"'

Additional Information

For a complete list of available query parameters and attributes for filtering and sorting, refer to the official API documentation.

• List all workspaces API documentation