List Workspaces

List workspaces in an organization.

External Documentation

To learn more, visit the Terraform Cloud documentation.

Basic Parameters

Parameter	Description
Organization Name	The name of the organization to list the workspaces of.
Query By Name	Fetch workspaces with a name that matches the search string using a fuzzy search.
Query By Tags	Fetch workspaces with a tag. If a comma separated list of tags is provided, results matching all of the tags are returned.
Sort	Allows sorting the organization's workspaces by a provided value.

Advanced Parameters

Parameter	Description
Exclude Tags	Fetch workspaces without a specified tag. If a comma separated list of tags is provided, workspaces with tags matching any of the tags are excluded.
Filter By Status	Return workspaces that match the status of a current run.
Page Number	Page number of results to retrieve. Defaults to the first page, if omitted when Page Size is provided.
Page Size	Number of results per page. Valid range is 1-100. Defaults to 20 if omitted when Page Number is provided.
Query By Project ID	Return workspaces in the specified project.
Tagged With Key	Return results to workspaces that are tagged with the provided key. For more information, please visit Terraform's documentation.
Tagged With Value	Return workspaces that are tagged with the provided value. For more information, please visit Terraform's documentation.
Wildcard Name	Restricts results to workspaces with partial matching, using * on prefix, suffix, or both. For more information, please visit Terraform's documentation.

Example Output

{
  "data": [
    {
      "id": "ws-6jrRyVDv1J8zQMB5",
      "type": "workspaces",
      "attributes": {
        "actions": {
          "is-destroyable": true
        },
        "allow-destroy-plan": true,
        "assessments-enabled": false,
        "auto-apply": false,
        "auto-apply-run-trigger": false,
        "auto-destroy-at": null,
        "auto-destroy-status": null,
        "auto-destroy-activity-duration": null,
        "inherits-project-auto-destroy": null,
        "created-at": "2021-08-16T21:22:49.566Z",
        "description": null,
        "environment": "default",
        "execution-mode": "agent",
        "file-triggers-enabled": true,
        "global-remote-state": false,
        "latest-change-at": "2021-08-16T21:22:49.566Z",
        "last-assessment-result-at" : "2021-08-17T21:20:12.908Z",
        "locked": true,
        "locked-reason": null,
        "name": "workspace-1",
        "oauth-client-name": null,
        "operations": true,
        "permissions": {
          "can-update": true,
          "can-destroy": true,
          "can-queue-run": true,
          "can-read-run": true,
          "can-read-variable": true,
          "can-update-variable": true,
          "can-read-state-versions": true,
          "can-read-state-outputs": true,
          "can-create-state-versions": true,
          "can-queue-apply": true,
          "can-lock": true,
          "can-unlock": true,
          "can-force-unlock": true,
          "can-read-settings": true,
          "can-manage-tags": true,
          "can-manage-run-tasks": true,
          "can-force-delete": true,
          "can-manage-assessments": true,
          "can-manage-ephemeral-workspaces": false,
          "can-read-assessment-results": true,
          "can-queue-destroy": true
        },
        "apply-duration-average": 35000,
        "plan-duration-average": 53000,
        "policy-check-failures": null,
        "queue-all-runs": false,
        "resource-count": 10,
        "run-failures": 3,
        "source": "tfe-api",
        "source-name": null,
        "source-url": null,
        "speculative-enabled": true,
        "structured-run-output-enabled": true,
        "tag-names": [],
        "terraform-version": "1.9.4",
        "trigger-prefixes": [],
        "updated-at": "2021-08-16T21:22:49.566Z",
        "vcs-repo": null,
        "vcs-repo-identifier": null,
        "working-directory": null,
        "workspace-kpis-runs-count": 8,
        "setting-overwrites": {
          "execution-mode": true,
          "agent-pool": true
        }
      },
      "links": {
        "self": "/api/v2/organizations/my-organization/workspaces/workspace-1",
        "self-html": "/app/my-organization/workspaces/workspace-1"
      },
      "relationships": {
        "agent-pool": {
          "data": {
            "id": "apool-QxGd2tRjympfMvQc",
            "type": "agent-pools"
          }
        },
        "current-configuration-version": {
          "data": null
        },
        "current-run": {
          "data": {
            "id": "run-hjy7ndEkmCtn31ps",
            "type": "runs"
          },
          "links": {
            "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
          }
        },
        "effective-tag-bindings": {
          "links": {
            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"
          }
        },
        "latest-run": { // Deprecated; same as current-run
          "data": {
            "id": "run-hjy7ndEkmCtn31ps",
            "type": "runs"
          },
          "links": {
            "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
          }
        },
        "current-state-version": {
          "data": {
            "id": "sv-hjy7ndEkmCtn31ps",
            "type": "state-versions"
          },
          "links": {
            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
          }
        },
        "current-configuration-version": {
          "data": {
            "id": "cv-hjy7ndEkmCtn31ps",
            "type": "configuration-versions"
          },
          "links": {
            "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
          }
        },
        "current-assessment-result": {
          "data": null
        },
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        },
        "outputs": {
          "data": [
            {
              "id": "wsout-hjy7ndEkmCtn31ps",
              "type": "workspace-outputs"
            },
            {
              "id": "wsout-hjy7ndEkmCtn31ps",
              "type": "workspace-outputs"
            }
          ],
          "links": {
            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
          }
        },
        "project": {
          "data": {
            "id": "prj-hjy7ndEkmCtn31ps",
            "type": "projects"
          }
        },
        "readme": {
          "data": null
        },
        "remote-state-consumers": {
          "links": {
            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
          }
        },
        "ssh-key": {
          "data": {
            "id": "sshkey-hjy7ndEkmCtn31ps",
            "type": "ssh-keys"
          },
          "links": {
            "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
          }
        },
        "locked-by": {
          "data": {
            "id": "user-hjy7ndEkmCtn31ps",
            "type": "users"
          },
          "links": {
            "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
          }
        },
        "tag-bindings": {
          "links": {
            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"
          }
        },
        "vars": {
          "data": [
            {
              "id": "var-hjy7ndEkmCtn31ps",
              "type": "vars"
            }
          ]
        },
      }
    },
  ],
  "links": {
    "first": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "next": null,
    "prev": null,
    "self": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "next-page": null,
      "page-size": 20,
      "prev-page": null,
      "total-count": 1,
      "total-pages": 1
    }
  }
}

Workflow Library Example

List Workspaces with Terraform Cloud and Send Results Via Email

Preview this Workflow on desktop