# List Shares

Launch stage: GA

`GET /api/2.1/unity-catalog/shares`

Gets an array of data object shares from the metastore. If the caller has the USE_SHARE privilege on the metastore, all shares are returned. Otherwise, only shares owned by the caller are returned.
 There is no guarantee of a specific ordering of the elements in the array.

API scopes: sharing

## Query parameters

- `max_results` (int32, optional)
  Maximum number of shares to return.
     - when set to 0, the page length is set to a server configured value (recommended);
     - when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
     - when set to a value less than 0, an invalid parameter error is returned;
     - If not set, all valid shares are returned (not recommended).
     - Note: The number of returned shares might be less than the specified max_results size, even zero.
     The only definitive indication that no further shares can be fetched is when the next_page_token is unset from the response.
  Constraints: `<= 1000`
- `page_token` (string, optional)
  Opaque pagination token to go to next page based on previous query.

## Returns

- `shares` (array of object, optional)
  An array of data share information objects.
  - `name` (string, optional)
    Name of the share.
  - `owner` (string, optional)
    Username of current owner of share.
  - `comment` (string, optional)
    User-provided free-form text description.
  - `storage_root` (string, optional)
    Storage root URL for the share.
  - `objects` (array of object, optional)
    A list of shared data objects within the share.
    - `name` (string, optional)
      A fully qualified name that uniquely identifies a data object.
       For example, a table's fully qualified name is in the format of `<catalog>.<schema>.<table>`,
    - `data_object_type` (string, optional)
      The type of the data object.
    - `added_at` (int64, optional)
      The time when this data object is added to the share, in epoch milliseconds.
    - `added_by` (string, optional)
      Username of the sharer.
    - `comment` (string, optional)
      A user-provided comment when adding the data object to the share.
    - `shared_as` (string, optional)
      A user-provided alias name for table-like data objects within the share.
      
       Use this field for table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE).
       For non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION), use `string_shared_as` instead.
      
       Important: For non-table objects, this field must be omitted entirely.
      
       Format: Must be a 2-part name `<schema_name>.<table_name>` (e.g., "sales_schema.orders_table")
       - Both schema and table names must contain only alphanumeric characters and underscores
       - No periods, spaces, forward slashes, or control characters are allowed within each part
       - Do not include the catalog name (use 2 parts, not 3)
      
       Behavior:
       - If not provided, the service automatically generates the alias as `<schema>.<table>` from the object's original name
       - If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
       - The `shared_as` name must be unique within the share
      
       Examples:
       - Valid: "analytics_schema.customer_view"
       - Invalid: "catalog.analytics_schema.customer_view" (3 parts not allowed)
       - Invalid: "analytics-schema.customer-view" (hyphens not allowed)
    - `cdf_enabled` (boolean, optional)
      Whether to enable cdf or indicate if cdf is enabled on the shared object.
    - `history_data_sharing_status` (string, optional)
      Whether to enable or disable sharing of data history. If not specified, the default is **DISABLED**.
      Possible values: `DISABLED`, `ENABLED`
    - `start_version` (int64, optional)
      The start version associated with the object.
       This allows data providers to control the lowest object version that is accessible by clients.
       If specified, clients can query snapshots or changes for versions >= start_version.
       If not specified, clients can only query starting from the version of the object at the time
       it was added to the share.
      
       NOTE: The start_version should be <= the `current` version of the object.
    - `status` (string, optional)
      One of: **ACTIVE**, **PERMISSION_DENIED**.
      Possible values: `ACTIVE`, `PERMISSION_DENIED`
    - `content` (string, optional)
      The content of the notebook file when the data object type is NOTEBOOK_FILE.
       This should be base64 encoded.
       Required for adding a NOTEBOOK_FILE, optional for updating, ignored for other types.
    - `string_shared_as` (string, optional)
      A user-provided alias name for non-table data objects within the share.
      
       Use this field for non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION).
       For table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE), use `shared_as` instead.
      
       Important: For table-like objects, this field must be omitted entirely.
      
       Format:
       - For VOLUME: Must be a 2-part name `<schema_name>.<volume_name>` (e.g., "data_schema.ml_models")
       - For FUNCTION: Must be a 2-part name `<schema_name>.<function_name>` (e.g., "udf_schema.calculate_tax")
       - For MODEL: Must be a 2-part name `<schema_name>.<model_name>` (e.g., "models.prediction_model")
       - For NOTEBOOK_FILE: Should be the notebook file name (e.g., "analysis_notebook.py")
       - All names must contain only alphanumeric characters and underscores
       - No periods, spaces, forward slashes, or control characters are allowed within each part
      
       Behavior:
       - If not provided, the service automatically generates the alias from the object's original name
       - If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
       - The `string_shared_as` name must be unique for objects of the same type within the share
      
       Examples:
       - Valid for VOLUME: "data_schema.training_data"
       - Valid for FUNCTION: "analytics.calculate_revenue"
       - Invalid: "catalog.data_schema.training_data" (3 parts not allowed for volumes)
       - Invalid: "data-schema.training-data" (hyphens not allowed)
    - `partitions` (array of object, optional)
      Array of partitions for the shared data.
      - `values` (array of object, optional)
        An array of partition values.
  - `created_at` (int64, optional)
    Time at which this share was created, in epoch milliseconds.
  - `created_by` (string, optional)
    Username of share creator.
  - `updated_at` (int64, optional)
    Time at which this share was updated, in epoch milliseconds.
  - `updated_by` (string, optional)
    Username of share updater.
  - `storage_location` (string, optional)
    Storage Location URL (full path) for the share.
- `next_page_token` (string, optional)
  Opaque token to retrieve the next page of results. Absent if there are no more pages.
   __page_token__ should be set to this value for the next request (for the next page of results).

## Response

```json
{
  "shares": [
    {
      "name": "string",
      "owner": "string",
      "comment": "string",
      "storage_root": "string",
      "objects": [
        {}
      ],
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "storage_location": "string"
    }
  ],
  "next_page_token": "string"
}
```