---
title: "List workspaces"
method: GET
path: "/v2/storage/branch/{branchId}/workspaces"
tags: ["Workspaces"]
---

# List workspaces

`GET /v2/storage/branch/{branchId}/workspaces`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/branch/{branchId}/workspaces`
- Auth: one of:
  - API key in header `X-StorageApi-Token`
  - API key in header `X-KBC-ManageApiToken`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/keboola/apis/keboola-storage-api/docs/v2/storage/branch/:branchId/workspaces/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns all workspaces for the project in the given branch. Use `default` as `branchId` (or the variant without
the branch prefix) to list workspaces of the default branch.

## Path parameters

- `branchId` string, required

## Response `200`

List of workspaces.

- WorkspaceDetailResponse[]
  - `id` integer, required: ID of the workspace.
  - `type` 'file' | 'table', required: Type of the workspace.
  - `name` string, nullable, required: Name of the workspace (schema name for table type).
  - `component` string, nullable, required: ID of the component that created the workspace.
  - `configurationId` string, nullable, required: ID of the configuration that created the workspace.
  - `configurationVersion` integer, nullable, required: Pinned configuration version.
  - `created` string, required: Date and time of workspace creation, ISO 8601 with a `+hhmm` offset.
  - `connection` union, required: Connection details for the workspace.
    - object
      - `backend` 'snowflake' | 'synapse' | 'exasol' | 'teradata' | 'bigquery' | 'postgres' | 'ducklake', required: Workspace backend type.
      - `region` string, required: Region of the workspace backend.
      - `host` string, required: Hostname of the workspace backend.
      - `database` string, nullable, required: Database name (project name for Snowflake).
      - `schema` string, nullable, required: Schema name.
      - `warehouse` string, nullable, required: Warehouse name (for Snowflake).
      - `user` string, required: Username for connecting to the workspace. Empty when loginType is "none" or "governed".
      - `loginType` 'default' | 'snowflake-legacy-service' | 'snowflake-person-sso' | 'snowflake-person-keypair' | 'snowflake-service-keypair' | 'none' | 'governed', required: Login type used for the connection. Value "none" means the workspace has no direct credentials and is intended for QueryService. Value "governed" means the same, and in addition only QueryService can obtain credentials for it. Create direct connection credentials later using the workspace credentials endpoint.
      - `ssoLoginAvailable` boolean, required: Indicates if SSO login is available.
      - `account` string: Snowflake account locator. Present only for Snowflake workspaces.
      - `role` string, nullable: Snowflake role of the workspace user. Present only for Snowflake workspaces.
    - object
      - `backend` string, required: File storage backend type (e.g., azure, aws).
      - `container` string, nullable, required: Container name for file storage.
      - `region` string, required: Region of the file storage.
  - `backendSize` string, nullable, required: Size of the backend (e.g., for Snowflake).
  - `statementTimeoutSeconds` integer, required: Statement timeout in seconds.
  - `creatorToken` object, required
    - `id` integer, required: ID of the token that created the workspace; 0 when the creator is not backed by a token.
    - `description` string, nullable, required: Description of the token.
  - `actor` ActorResponse, required: Who performed the action and through which credential.
    - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
    - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
    - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
    - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
  - `readOnlyStorageAccess` boolean, required: Indicates if read-only storage access is enabled.
  - `platformUsageType` 'service' | 'user' | 'reader', nullable, required: Platform usage type.
  - `state` 'active' | 'deactivated', required: Lifecycle state of the workspace. A deactivated workspace is kept listed so its owner can delete it, but its backend identity is disabled and cannot be connected to; contact support to reactivate it.
  - `lastActivityAt` string, nullable, required: Last observed workspace use (backend login or Storage job), ISO 8601 with a `+hhmm` offset. May be a seeded floor for an unused workspace; null when unknown.
  - `warnAt` string, nullable, required: Projected date retention would warn this workspace, ISO 8601 with a `+hhmm` offset. It can move when the workspace is used; null when retention does not apply or activity has not been synced recently.
  - `deactivateAt` string, nullable, required: When retention will deactivate this unused workspace, ISO 8601 with a `+hhmm` offset. Null unless the owner has been warned. Connecting to the workspace cancels it. Can lie in the past while retention only notifies.
  - `deleteAt` string, nullable, required: When retention will delete this deactivated workspace, ISO 8601 with a `+hhmm` offset. Null unless the workspace is deactivated. Support can reactivate it until then.

## Other responses

- `422`: Returned when a workspace uses an unsupported backend (`workspace.backendNotSupported`).

---

[API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)