--- updatedAt: 2026-05-28T08:16:45.000Z agentTools: projectIndex: https://docs.scalr.io/llms.txt --- # Get a Workspace Show details of a specific workspace. # OpenAPI definition ```json { "components": { "schemas": { "Workspace": { "description": "A Workspace is where Terraform runs are performed for a specific configuration, and where the resulting\nstate file(s) are stored.\n\nWorkspaces belong to environments and can have `variables` configured to provide inputs to the configuration,\nauthenticate providers etc.\n\nThe extra fields below are not available in response by default. Ask for them explicitly in the query parameter `fields[workspaces]`:\n* module", "properties": { "attributes": { "properties": { "apply-schedule": { "description": "Cron expression for scheduled runs. Time should be in UTC.", "nullable": true, "readOnly": true, "type": "string" }, "auto-apply": { "description": "Indicates whether `terraform apply` should automatically run\nwhen terraform plan ends without error. Default `false`.", "type": "boolean" }, "auto-destroy-days": { "description": "How many days should the workspace exist.", "enum": [ 1, 2, 7, 14 ], "nullable": true, "type": "integer" }, "auto-destroy-status": { "description": "The status of scheduled destruction of the workspace.", "nullable": true, "readOnly": true, "type": "string" }, "auto-destroy-time": { "description": "When should the destruction of the workspace begin.", "format": "date-time", "nullable": true, "readOnly": true, "type": "string" }, "auto-queue-runs": { "default": "skip_first", "description": "Indicates if runs have to be queued automatically when a new configuration version is uploaded.\n`skip_first` - after the very first configuration version is uploaded into the workspace the run will not be triggered.\n But the following configurations will do. This is the default behavior.\n`on_create_only` - single run will be triggered only when the workspace is created and the first configuration version is uploaded.\n Subsequent configurations will not trigger runs.\n`always` - runs will be triggered automatically on every upload of the configuration version.\n`never` - configuration versions are uploaded into the workspace, but runs will not be triggered.", "enum": [ "always", "never", "skip_first", "on_create_only" ], "type": "string" }, "created-at": { "description": "The resource creation timestamp.", "format": "date-time", "readOnly": true, "type": "string" }, "deletion-protection-changed-by-email": { "description": "The email of a user who toggled deletion protection.", "nullable": true, "readOnly": true, "type": "string" }, "deletion-protection-enabled": { "description": "Designates whether deletion protection is enabled.", "type": "boolean" }, "destroy-schedule": { "description": "Cron expression for scheduled destroy runs. Time should be in UTC.", "nullable": true, "readOnly": true, "type": "string" }, "environment-type": { "description": "The type of the Scalr Workspace environment.", "enum": [ "production", "staging", "testing", "development", "unmapped" ], "type": "string" }, "execution-mode": { "default": "remote", "description": "Which execution mode to use. Valid values are `remote` and `local`.\nWhen set to `local`, the workspace will be used for state storage only.", "enum": [ "remote", "local" ], "type": "string" }, "favorite": { "description": "Indicates whether the workspace is marked as favorite by the current user.", "readOnly": true, "type": "boolean" }, "force-latest-run": { "description": "Indicates whether `force run` should automatically apply to latest run.\nDefault `false`.", "type": "boolean" }, "has-resources": { "description": "Indicates whether the workspace's current state version contains terraform resources.", "readOnly": true, "type": "boolean" }, "hooks": { "nullable": true, "properties": { "post-apply": { "description": "Command that should be run after terraform apply operation executed.", "nullable": true, "type": "string" }, "post-plan": { "description": "Command that should be run after terraform plan operation executed.", "nullable": true, "type": "string" }, "pre-apply": { "description": "Command that should be run before terraform apply operation executed.", "nullable": true, "type": "string" }, "pre-init": { "description": "Command that should be run before terraform init operation executed.", "nullable": true, "type": "string" }, "pre-plan": { "description": "Command that should be run before terraform plan operation executed.", "nullable": true, "type": "string" } }, "type": "object" }, "iac-platform": { "default": "terraform", "description": "The IaC platform of this workspace.", "enum": [ "terraform", "opentofu" ], "type": "string" }, "lock-reason": { "description": "The reason (if any) that the workspace has been locked.", "nullable": true, "readOnly": true, "type": "string" }, "locked": { "description": "Indicates whether the workspace is locked for operations. The `lock-reason` attribute\ncarries the explanation.\n\nThis semaphore is acquired and released by terraform apply and can also manage it with\nLock/Unlock Workspace.\n\nDefault: `false`", "readOnly": true, "type": "boolean" }, "name": { "description": "Workspace name which must be unique within the environment.\n\nComprises letters, numbers, `-`, and `_` only.", "maxLength": 255, "type": "string" }, "operations": { "deprecated": true, "description": "The attribute `operations` is deprecated. Use `execution-mode` instead.", "type": "boolean" }, "permissions": { "readOnly": true, "type": "object" }, "remote-backend": { "description": "Manages if Scalr exports the remote backend configuration and state storage for your infrastructure management. Disabling this feature will also prevent the ability to perform state locking, which ensures that concurrent operations do not conflict. Additionally, it will disable the capability to initiate CLI-driven runs through Scalr.", "type": "boolean" }, "remote-state-sharing": { "description": "Specifies if the state is shared within the environment.", "type": "boolean" }, "run-operation-timeout": { "description": "The timeout for the Terraform Run operations (in minutes).", "nullable": true, "type": "integer" }, "terraform-version": { "description": "The version of Terraform the workspace performs runs on. If omitted, the system default version is assigned.", "type": "string" }, "terragrunt": { "nullable": true, "properties": { "include-external-dependencies": { "default": false, "description": "Indicates whether the workspace includes external dependencies.", "type": "boolean" }, "use-run-all": { "default": false, "description": "Indicates whether the workspace uses `terragrunt run-all`.", "type": "boolean" }, "version": { "description": "The version of Terragrunt the workspace performs runs on.", "type": "string" } }, "required": [ "version" ], "type": "object" }, "updated-at": { "description": "The resource last update timestamp.", "format": "date-time", "nullable": true, "readOnly": true, "type": "string" }, "updated-by-email": { "description": "The email of the last user, that updated this workspace.", "nullable": true, "readOnly": true, "type": "string" }, "var-files": { "default": [], "description": "The list of Terraform variables files.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "vcs-repo": { "nullable": true, "properties": { "branch": { "description": "Branch of a repository the workspace is associated with.\nIf omitted, the repository default branch will be used.\n\nThis option conflicts with `version_constraint`.", "nullable": true, "type": "string" }, "dry-runs-enabled": { "default": true, "description": "When true once a pull request into the vcs-repo.branch is opened, every push\nto a pull request's branch will trigger a dry run in the workspace. Default `true`", "type": "boolean" }, "identifier": { "description": "A reference to your VCS repository.\n\nFor GitHub, GitHub Enterprise and GitLab the format is `/`.\nAzure DevOps Services has the format `//`.", "type": "string" }, "ingress-submodules": { "default": false, "description": "Specifies whether git submodules should be fetched when cloning the VCS repository.", "type": "boolean" }, "path": { "default": "", "deprecated": true, "description": "The attribute `vcs-repo.path` is deprecated. Use working-directory and trigger-prefixes instead.", "nullable": true, "type": "string" }, "trigger-patterns": { "description": "List of path patterns in gitignore format, whose changes will trigger a run for the\nworkspace using this binding when the CV is created.\nConflicts with 'trigger-prefixes'.\nIf 'trigger-patterns' and 'trigger-prefixes' are omitted, any change in the configuration version root will trigger a new run.", "nullable": true, "type": "string" }, "trigger-prefixes": { "default": [], "description": "List of paths (relative to the configuration version root), whose changes will trigger a run for the\nworkspace using this binding when the CV is created.\nConflicts with 'trigger-patterns'.\nIf 'trigger-patterns' and 'trigger-prefixes' are omitted, any change in the configuration version root will trigger a new run.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "version-constraint": { "description": "Terraform-like version constraint used to trigger a run for matching Git tags.\n\nOnly stable tags are supported in version ranges. Pre-release tags\n(e.g. `-rc`, `-beta`) must be specified exactly, e.g. `1.2.0-rc1`,\nto trigger a run.\n\nThis option conflicts with `branch`.", "nullable": true, "type": "string" } }, "required": [ "identifier" ], "type": "object" }, "vcs-repo-inaccessible": { "description": "True when the workspace VCS repository returned 403 for its account integration. Configuration versions from this repository cannot be downloaded.", "readOnly": true, "type": "boolean" }, "working-directory": { "description": "A relative path where Terraform commands will execute in.", "maxLength": 255, "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "id": { "readOnly": true, "type": "string" }, "links": { "properties": { "self": { "readOnly": true, "type": "string" } }, "readOnly": true, "type": "object" }, "relationships": { "properties": { "agent-pool": { "description": "The ID of the agent pool used to execute run stages. Overrides the default account-level and environment-level pools.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "agent-pools", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "configuration-version": { "description": "The latest uploaded configuration version.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "configuration-versions", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "created-by": { "description": "The user, who has triggered the run.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "users", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "current-run": { "description": "The latest non-dry Run in this workspace.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "runs", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "drift-report": { "description": "The drift report for the workspace.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "drift-reports", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "environment": { "description": "The environment this workspace belongs to.", "properties": { "data": { "properties": { "id": { "type": "string" }, "type": { "enum": [ "environments", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "latest-configuration-version": { "description": "The configuration version of the latest non-dry Run in this workspace.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "configuration-versions", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "latest-run": { "deprecated": true, "description": "The latest non-dry Run in this workspace (deprecated, same as current).", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "runs", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "locked-by": { "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "users", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "locked-by-run": { "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "runs", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "module": { "description": "The ID of the module.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "modules", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "module-version": { "description": "The ID of the module version.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "module-versions", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "readme-id": { "description": "The readme for the workspace.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "workspace-readme", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "runner-image-version": { "description": "Workspace runner image version for Scalr-managed agent pools.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "container-image-versions", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "ssh-key": { "description": "The SSH key used to this workspace.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "account-ssh-keys", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "tags": { "properties": { "data": { "items": { "properties": { "id": { "type": "string" }, "type": { "enum": [ "tags", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "nullable": true, "type": "array" } }, "required": [ "data" ], "type": "object" }, "updated-by": { "description": "The last user, that updated this workspace.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "users", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "vcs-provider": { "description": "VCS provider of the Run's workspace", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "vcs-providers", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" } }, "required": [ "environment" ], "type": "object" }, "type": { "enum": [ "workspaces" ], "type": "string" } }, "required": [ "type", "attributes", "relationships" ], "type": "object" }, "WorkspaceDocument": { "description": "JSON:API Document.\n\nsee: https://jsonapi.org/format/#document-structure", "properties": { "data": { "$ref": "#/components/schemas/Workspace" }, "included": { "items": { "type": "object" }, "readOnly": true, "type": "array" }, "meta": { "readOnly": true, "type": "object" } }, "type": "object" } }, "securitySchemes": { "API-Key": { "scheme": "bearer", "type": "http" } } }, "info": { "description": "Scalr IACP API", "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "title": "Scalr IACP API", "version": "unversioned" }, "openapi": "3.0.0", "paths": { "/workspaces/{workspace}": { "get": { "description": "Show details of a specific workspace.", "operationId": "get_workspace", "parameters": [ { "description": "The workspace ID to show.", "in": "path", "name": "workspace", "required": true, "schema": { "type": "string" } }, { "description": "The comma-separated list of relationship paths.", "explode": false, "in": "query", "name": "include", "required": false, "schema": { "items": { "enum": [ "agent-pool", "configuration-version", "created-by", "current-run", "drift-report", "environment", "latest-configuration-version", "latest-run", "locked-by", "locked-by-run", "module", "module-version", "readme-id", "runner-image-version", "tags", "updated-by", "vcs-provider" ], "type": "string" }, "type": "array" } }, { "description": "The value of the fields[resource-type] parameter is a comma-separated list that refers to the name of the fields to be returned for the resource. An empty value indicates that no fields should be returned.", "explode": true, "in": "query", "name": "fields", "required": false, "schema": { "properties": { "agent-pools": { "description": "The comma-separated list of fields to return in response for AgentPool resource.", "type": "string" }, "configuration-versions": { "description": "The comma-separated list of fields to return in response for ConfigurationVersion resource.", "type": "string" }, "container-image-versions": { "description": "The comma-separated list of fields to return in response for ContainerImageVersion resource.", "type": "string" }, "drift-reports": { "description": "The comma-separated list of fields to return in response for DriftReport resource.", "type": "string" }, "environments": { "description": "The comma-separated list of fields to return in response for Environment resource.", "type": "string" }, "module-versions": { "description": "The comma-separated list of fields to return in response for ModuleVersion resource.", "type": "string" }, "modules": { "description": "The comma-separated list of fields to return in response for Module resource.", "type": "string" }, "runs": { "description": "The comma-separated list of fields to return in response for Run resource.", "type": "string" }, "tags": { "description": "The comma-separated list of fields to return in response for Tag resource.", "type": "string" }, "users": { "description": "The comma-separated list of fields to return in response for User resource.", "type": "string" }, "vcs-providers": { "description": "The comma-separated list of fields to return in response for VcsProvider resource.", "type": "string" }, "workspace-readme": { "description": "The comma-separated list of fields to return in response for WorkspaceReadme resource.", "type": "string" }, "workspaces": { "description": "The comma-separated list of fields to return in response for Workspace resource.", "type": "string" } }, "type": "object" }, "style": "deepObject" } ], "responses": { "200": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/WorkspaceDocument" } } }, "description": "Success." }, "404": { "description": "Workspace not found, or user unauthorized to perform action." }, "4XX": { "description": "Client error." }, "5XX": { "description": "Server error." } }, "summary": "Get a Workspace", "tags": [ "workspaces" ], "x-mcp-tool": true, "x-resource": "Workspace", "x-service": "tf-api" } } }, "security": [ { "API-Key": [] } ], "servers": [ { "url": "https://{Domain}/api/iacp/v3", "variables": { "Domain": { "default": "example.scalr.io", "description": "Domain where Scalr is hosted" } } } ] } ``` # Sibling pages * [List Workspaces](https://docs.scalr.io/scalr/reference/get_workspaces.md) * [Create a Workspace](https://docs.scalr.io/scalr/reference/create_workspace.md) * [Delete a Workspace](https://docs.scalr.io/scalr/reference/delete_workspace.md) * [Update a Workspace](https://docs.scalr.io/scalr/reference/update_workspace.md) * [Lock a Workspace](https://docs.scalr.io/scalr/reference/lock_workspace.md) * [Resync a Workspace](https://docs.scalr.io/scalr/reference/resync_workspace.md) * [Set scheduled runs for the workspace](https://docs.scalr.io/scalr/reference/set_schedule.md) * [Unlock a Workspace](https://docs.scalr.io/scalr/reference/unlock_workspace.md) * [List workspace's outputs.](https://docs.scalr.io/scalr/reference/get_workspace_outputs.md) * [Delete workspace's tags](https://docs.scalr.io/scalr/reference/delete_workspace_tags.md) * [List workspace's tags](https://docs.scalr.io/scalr/reference/list_workspace_tags.md) * [Replace workspace's tags](https://docs.scalr.io/scalr/reference/replace_workspace_tags.md) * [Add tags to the workspace](https://docs.scalr.io/scalr/reference/add_workspace_tags.md)