# List asset shares

Retrieves a list of all users and groups to whom the specified asset is shared, and their access level. This operation supports query string parameters for pagination of results. 

> Note: For pagination guidance, refer to Token-based pagination.

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

## Header parameters:

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

## Query parameters:

  - `assetType` (string, required)
    The type of the asset. Used in combination with assetId to determine the asset.
    Enum: "sheet", "report", "sight", "workspace", "collection", "file"

  - `assetId` (string, required)
    The ID of the asset being accessed. It's used in combination with assetType to determine the asset.

Depending on the asset, this may be a numeric or string value.
    Example: "1234567890"

  - `maxItems` (integer)
    Request query parameter used in 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"

  - `sharingInclude` (string)
    When applicable for the specific object this parameter defines the scope of the share. Possible values are ITEM or WORKSPACE. ITEM is an item-level share (that is, the specific object to which the share applies is shared with the user or group). WORKSPACE is a workspace-level share (that is, the workspace that contains the object to which the share applies is shared with the user or group).
    Enum: "ITEM", "WORKSPACE"

## 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"

  - `items` (array)

  - `items.id` (string, required)
    The ID of the share.
    Example: "AAAMCmYGFOeE"

  - `items.email` (string)
    User's primary email address for user shares.
    Example: "test.email@smartsheet.com"

  - `items.userId` (number)
    User ID if the share is a user share.
    Example: 9876543210

  - `items.groupId` (number)
    Group ID if the share is a group share.
    Example: 1234567890

  - `items.name` (string)
    If present, the name of the user or group to which the asset is shared.
    Example: "Example Name"

  - `items.type` (string, required)
    The type of this share. One of the following values: GROUP or USER.
    Example: "USER"

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

  - `items.scope` (string, required)
    The scope of this share. One of the following values:
  * ITEM: an item-level share (that is, the specific object to which the share applies is shared with
    the user or group).
  * WORKSPACE: a workspace-level share (that is, the workspace that contains the asset to which the
    share applies is shared with the user or group).
    Enum: "ITEM", "WORKSPACE"

## 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.