# List Registered Models

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

List registered models. You can list registered models under a particular schema,
 or list all registered models in the current metastore.

 The returned models are filtered based on the privileges of the calling user.
 For example, the metastore admin is able to list all the registered models.
 A regular user needs to be the owner or have the **EXECUTE** privilege
 on the registered model to receive the registered models in the response.
 For the latter case, the caller must also be the owner or have the **USE_CATALOG**
 privilege on the parent catalog and the **USE_SCHEMA** privilege on the parent schema.

 There is no guarantee of a specific ordering of the elements in the response.

 PAGINATION BEHAVIOR: The API is by default paginated, a page may contain zero results while still providing a next_page_token.
 Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

## Query parameters

- `catalog_name` (string, optional)
  The identifier of the catalog under which to list registered models.
               If specified, schema_name must be specified.
- `schema_name` (string, optional)
  The identifier of the schema under which to list registered models.
               If specified, catalog_name must be specified.
- `include_browse` (boolean, optional)
  Whether to include registered models in the response for which the principal can only access selective metadata for
- `max_results` (int64, optional)
  Max number of registered models to return.
   
   If both catalog and schema are specified:
   - when max_results is not specified, the page length is set to a server configured value (10000, as of 4/2/2024).
   - when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 4/2/2024);
   - when set to 0, the page length is set to a server configured value (10000, as of 4/2/2024);
   - when set to a value less than 0, an invalid parameter error is returned;
   
   If neither schema nor catalog is specified:
   - when max_results is not specified, the page length is set to a server configured value (100, as of 4/2/2024).
   - when set to a value greater than 0, the page length is the minimum of this value and a server configured value (1000, as of 4/2/2024);
   - when set to 0, the page length is set to a server configured value (100, as of 4/2/2024);
   - when set to a value less than 0, an invalid parameter error is returned;
  Constraints: `<= 100`
- `page_token` (string, optional)
  Opaque token to send for the next page of results (pagination).

## Returns

- `registered_models` (array of object, optional)
  - `name` (string, optional)
    The name of the registered model
  - `catalog_name` (string, optional)
    The name of the catalog where the schema and the registered model reside
  - `schema_name` (string, optional)
    The name of the schema where the registered model resides
  - `owner` (string, optional)
    The identifier of the user who owns the registered model
  - `comment` (string, optional)
    The comment attached to the registered model
    Constraints: `[ 1 .. 65536 ] characters`
  - `storage_location` (string, optional)
    The storage location on the cloud under which model version data files are stored
  - `metastore_id` (string, optional)
    The unique identifier of the metastore
  - `full_name` (string, optional)
    The three-level (fully qualified) name of the registered model
  - `created_at` (int64, optional)
    Creation timestamp of the registered model in milliseconds since the Unix epoch
  - `created_by` (string, optional)
    The identifier of the user who created the registered model
  - `updated_at` (int64, optional)
    Last-update timestamp of the registered model in milliseconds since the Unix epoch
  - `updated_by` (string, optional)
    The identifier of the user who updated the registered model last time
  - `aliases` (array of object, optional)
    List of aliases associated with the registered model
    - `alias_name` (string, optional)
      Name of the alias, e.g. 'champion' or 'latest_stable'
    - `version_num` (int64, optional)
      Integer version number of the model version to which this alias points.
    - `id` (string, optional)
      The unique identifier of the alias
    - `model_name` (string, optional)
      The name of the parent registered model of the model version, relative to parent schema
    - `catalog_name` (string, optional)
      The name of the catalog containing the model version
    - `schema_name` (string, optional)
      The name of the schema containing the model version, relative to parent catalog
  - `browse_only` (boolean, optional)
    Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.
- `next_page_token` (string, optional)
  Opaque token for pagination. Omitted if there are no more results. page_token should
   be set to this value for fetching the next page.

## Response

```json
{
  "registered_models": [
    {
      "name": "string",
      "catalog_name": "string",
      "schema_name": "string",
      "owner": "string",
      "comment": "string",
      "storage_location": "string",
      "metastore_id": "string",
      "full_name": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "aliases": [
        {}
      ],
      "browse_only": true
    }
  ],
  "next_page_token": "string"
}
```