# List Recipients

Launch stage: GA

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

Gets an array of all share recipients within the current metastore where:
 
   * the caller is a metastore admin, or
   * the caller is the owner.
 There is no guarantee of a specific ordering of the elements in the array.

API scopes: sharing

## Query parameters

- `data_recipient_global_metastore_id` (string, optional)
  If not provided, all recipients will be returned.
   If no recipients exist with this ID, no results will be returned.
- `max_results` (int32, optional)
  Maximum number of recipients 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 recipients are returned (not recommended).
    - Note: The number of returned recipients might be less than the specified max_results size, even zero.
   The only definitive indication that no further recipients 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

- `recipients` (array of object, optional)
  An array of recipient information objects.
  - `name` (string, optional)
    Name of Recipient.
  - `authentication_type` (string, optional)
    Possible values: `TOKEN`, `DATABRICKS`, `OIDC_FEDERATION`, `OAUTH_CLIENT_CREDENTIALS`
  - `sharing_code` (string, optional)
    The one-time sharing code provided by the data recipient. This field is only present when the __authentication_type__ is **DATABRICKS**.
  - `data_recipient_global_metastore_id` (string, optional)
    The global Unity Catalog metastore id provided by the data recipient.
     This field is only present when the __authentication_type__ is **DATABRICKS**.
     The identifier is of format __cloud__:__region__:__metastore-uuid__.
  - `owner` (string, optional)
    Username of the recipient owner.
  - `comment` (string, optional)
    Description about the recipient.
  - `ip_access_list` (object, optional)
    IP Access List
    - `allowed_ip_addresses` (array of string, optional)
      Allowed IP Addresses in CIDR notation. Limit of 100.
  - `properties_kvpairs` (object, optional)
    Recipient properties as map of string key-value pairs.
     When provided in update request, the specified properties will override the existing
     properties. To add and remove properties, one would need to perform a read-modify-write.
    - `properties` (object, optional)
      A map of key-value properties attached to the securable.
  - `expiration_time` (int64, optional)
    Expiration timestamp of the token, in epoch milliseconds.
  - `activation_url` (string, optional)
    Full activation url to retrieve the access token.
     It will be empty if the token is already retrieved.
  - `activated` (boolean, optional)
    A boolean status field showing whether the Recipient's activation URL has been exercised or not.
  - `created_at` (int64, optional)
    Time at which this recipient was created, in epoch milliseconds.
  - `created_by` (string, optional)
    Username of recipient creator.
  - `tokens` (array of object, optional)
    This field is only present when the __authentication_type__ is **TOKEN**.
    - `id` (string, optional)
      Unique ID of the recipient token.
    - `created_at` (int64, optional)
      Time at which this recipient token was created, in epoch milliseconds.
    - `created_by` (string, optional)
      Username of recipient token creator.
    - `activation_url` (string, optional)
      Full activation URL to retrieve the access token. It will be empty if the token is already retrieved.
    - `expiration_time` (int64, optional)
      Expiration timestamp of the token in epoch milliseconds.
    - `updated_at` (int64, optional)
      Time at which this recipient token was updated, in epoch milliseconds.
    - `updated_by` (string, optional)
      Username of recipient token updater.
  - `updated_at` (int64, optional)
    Time at which the recipient was updated, in epoch milliseconds.
  - `updated_by` (string, optional)
    Username of recipient updater.
  - `cloud` (string, optional)
    Cloud vendor of the recipient's Unity Catalog Metastore.
     This field is only present when the __authentication_type__ is **DATABRICKS**.
  - `region` (string, optional)
    Cloud region of the recipient's Unity Catalog Metastore.
     This field is only present when the __authentication_type__ is **DATABRICKS**.
  - `metastore_id` (string, optional)
    Unique identifier of recipient's Unity Catalog Metastore.
     This field is only present when the __authentication_type__ is **DATABRICKS**.
  - `id` (string, optional)
    [Create,Update:IGN] common - id of the recipient
- `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
{
  "recipients": [
    {
      "name": "string",
      "authentication_type": "string",
      "sharing_code": "string",
      "data_recipient_global_metastore_id": "string",
      "owner": "string",
      "comment": "string",
      "ip_access_list": {},
      "properties_kvpairs": {},
      "expiration_time": 0,
      "activation_url": "string",
      "activated": true,
      "created_at": 0,
      "created_by": "string",
      "tokens": [
        {}
      ],
      "updated_at": 0,
      "updated_by": "string",
      "cloud": "string",
      "region": "string",
      "metastore_id": "string",
      "id": "string"
    }
  ],
  "next_page_token": "string"
}
```