# List

Launch stage: GA

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

Gets an array of catalogs in the metastore.
 If the caller is the metastore admin, all catalogs will be retrieved.
 Otherwise, only catalogs owned by the caller (or for which the caller has the **USE_CATALOG** privilege) will be retrieved.
 There is no guarantee of a specific ordering of the elements in the array.

 NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.

 PAGINATION BEHAVIOR: When using pagination (max_results >= 0), 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

- `include_browse` (boolean, optional)
  Whether to include catalogs in the response for which the principal can only access selective metadata for
- `max_results` (int32, optional)
  Maximum number of catalogs 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 catalogs are returned (not recommended).
   - Note: The number of returned catalogs might be less than the specified max_results size, even zero.
     The only definitive indication that no further catalogs 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.
- `include_unbound` (boolean, optional)
  Whether to include catalogs not bound to the workspace.
   Effective only if the user has permission to update the catalog–workspace binding.

## Returns

Returns a list of CatalogInfo objects.

## Response

```json
{
  "catalogs": [
    {
      "name": "string",
      "owner": "string",
      "comment": "string",
      "storage_root": "string",
      "enable_predictive_optimization": "string",
      "catalog_type": "string",
      "provider_name": "string",
      "share_name": "string",
      "connection_name": "string",
      "metastore_id": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "storage_location": "string",
      "isolation_mode": "string",
      "effective_predictive_optimization_flag": {},
      "browse_only": true,
      "provisioning_info": {},
      "full_name": "string",
      "securable_type": "string",
      "custom_max_retention_hours": 0,
      "managed_encryption_settings": {},
      "properties": {},
      "options": {}
    }
  ],
  "next_page_token": "string"
}
```