List workspaces in an organization.

External Documentation

To learn more, visit the Terraform Cloud documentation.

​
Basic Parameters

ParameterDescription
Organization NameThe name of the organization to list the workspaces of.
Query By NameFetch workspaces with a name that matches the search string using a fuzzy search.
Query By TagsFetch workspaces with a tag. If a comma separated list of tags is provided, results matching all of the tags are returned.
SortAllows sorting the organization’s workspaces by a provided value.

​
Advanced Parameters

ParameterDescription
Exclude TagsFetch 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 StatusReturn workspaces that match the status of a current run.
Page NumberPage number of results to retrieve. Defaults to the first page, if omitted when Page Size is provided.
Page SizeNumber of results per page. Valid range is 1-100. Defaults to 20 if omitted when Page Number is provided.
Query By Project IDReturn workspaces in the specified project.
Tagged With KeyReturn results to workspaces that are tagged with the provided key. For more information, please visit Terraform’s documentation.
Tagged With ValueReturn workspaces that are tagged with the provided value. For more information, please visit Terraform’s documentation.
Wildcard NameRestricts 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

Was this page helpful?