# List workspaces

Retrieves a list of workspaces that the user has access to. It returns metadata for the workspaces only and doesn't include nested sub-structures.

> Tip: Set paginationType=token to use token-based pagination. 

> See also: Pagination - SDK examples demonstrates listing workspaces with token-based pagination.

Endpoint: GET /workspaces
Version: 2.0.0
Security: APIToken, OAuth2

## Header parameters:

  - `Authorization` (string)
    API Access Token used to authenticate requests to Smartsheet APIs.

  - `smartsheet-integration-source` (string)
    Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

- Integration source type
- Organization name
- Integration source name 

Format:


TYPE,OrgName,SourceName


Examples: 

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater
    Example: "AI,SampleOrg,My-AI-Connector-v2"

## Query parameters:

  - `accessApiLevel` (number)
    Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

  - `paginationType` (string)
    Specifies the type of pagination to use. When set to 'token', enables
token-based pagination.
    Enum: "token"

  - `maxItems` (integer)
    Request query parameter used in ListWorkspaces endpoints that support token based pagination.

The maximum amount of items to return in the response. The default and minimum are 100.
    Example: 100

  - `lastKey` (string)
    The lastKey token returned from the previous page of results. If not specified,
the first page of results is returned.
    Example: "abcDefGhIjKlMnOpQrStUvWxYz"

  - `includeAll` (boolean)
    If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize
(they are ignored if includeAll=true is specified).

DEPRECATED - As early as the sunset date specified in this 
Changelog entry, this request parameter will no longer be supported.

Refer to the following articles for examples of listing workspaces with token-based pagination: 

- Pagination
- Pagination - SDK examples

  - `page` (number)
    Which page to return. Defaults to 1 if not specified. If you specify a value
greater than the total number of pages, the last page of results is returned.

DEPRECATED - As early as the sunset date specified in this
Changelog entry, this request parameter will no longer be supported.

Refer to the following articles for examples of listing workspaces with token-based pagination: 

- Pagination
- Pagination - SDK examples

  - `pageSize` (number)
    The maximum number of items to return per page. Unless otherwise stated for a
specific endpoint, defaults to 100. If only page is specified, defaults to a
page size of 100. For reports, the default is 100 rows. If you need larger
sets of data from your report, returns a maximum of 10,000 rows per request.

DEPRECATED - As early as the sunset date specified in this
Changelog entry, this request parameter will no longer be supported.

Refer to the following articles for examples of listing workspaces with token-based pagination: 

- Pagination
- Pagination - SDK examples

## Response 200 fields (application/json):

  - `lastKey` (string)
    A token that is used to retrieve the next page of results when passed as the
lastKey query parameter. This value will be absent when there are no 
further pages.
    Example: "abcDefGhIjKlMnOpQrStUvWxYz"

  - `data` (array)

  - `data.id` (number)
    Workspace ID.

  - `data.name` (string)
    Workspace name.

  - `data.accessLevel` (string)
    Enum: "ADMIN", "COMMENTER", "EDITOR", "EDITOR_SHARE", "OWNER", "VIEWER"

  - `data.permalink` (string)
    URL that represents a direct link to the workspace in Smartsheet.

  - `pageNumber` (number)
    DEPRECATED - As early as the sunset date specified in this 
[Changelog entry](/api/smartsheet/changelog#2025-08-04), this response property will not be part 
of the response.

The current page in the full result set that the data array represents.
NOTE when a page number greater than totalPages is requested, the last
page is instead returned.
    Example: 1

  - `pageSize` (number,null)
    DEPRECATED - As early as the sunset date specified in this 
[Changelog entry](/api/smartsheet/changelog#2025-08-04), this response property will not be part 
of the response.

The number of items in a page. Omitted if there is no limit to page size
(and hence, all results are included). Unless otherwise specified, this
defaults to 100 for most endpoints. Only present when using page-based pagination.
    Example: 50

  - `totalPages` (number)
    DEPRECATED - As early as the sunset date specified in this 
[Changelog entry](/api/smartsheet/changelog#2025-08-04), this response property will not be part 
of the response.

The total number of pages in the full result set. Only present when
using page-based pagination.
    Example: 25

  - `totalCount` (number)
    DEPRECATED - As early as the sunset date specified in this 
[Changelog entry](/api/smartsheet/changelog#2025-08-04), this response property will not be part 
of the response.

The total number of items in the full result set. Only present when
using page-based pagination.
    Example: 136

## Response default fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.