# Method: users.list

Retrieves a paginated list of either deleted users or all users in a domain.

### HTTP request

`GET https://admin.googleapis.com/admin/directory/v1/users`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Query parameters

| Parameters ||
|---|---|
| `customFieldMask` | `string` A comma-separated list of schema names. All fields from these schemas are fetched. This should only be set when `projection=custom`. |
| `customer` | `string` The unique ID for the customer's Google Workspace account. In case of a multi-domain account, to fetch all users for a customer, use this field instead of `domain`. You can also use the `my_customer` alias to represent your account's `customerId`. The `customerId` is also returned as part of the [Users](https://developers.google.com/workspace/admin/directory/v1/reference/users) resource. You must provide either the `customer` or the `domain` parameter. |
| `domain` | `string` The domain name. Use this field to get users from only one domain. To return all domains for a customer account, use the `customer` query parameter instead. Either the `customer` or the `domain` parameter must be provided. |
| `event` | ``enum (`https://developers.google.com/workspace/admin/directory/reference/rest/v1/users/list#Event`)`` Event on which subscription is intended (if subscribing) |
| `maxResults` | `integer` Maximum number of results to return. |
| `orderBy` | ``enum (`https://developers.google.com/workspace/admin/directory/reference/rest/v1/users/list#OrderBy`)`` Property to use for sorting results. |
| `pageToken` | `string` Token to specify next page in the list. The page token is only valid for three days. |
| `projection` | ``enum (`https://developers.google.com/workspace/admin/directory/reference/rest/v1/users/list#Projection`)`` What subset of fields to fetch for this user. |
| `query` | `string` Query string for searching user fields. For more information on constructing user queries, see [Search for Users](https://developers.google.com/workspace/admin/directory/v1/guides/search-users). |
| `showDeleted` | `string` If set to `true`, retrieves the list of deleted users. (Default: `false`) |
| `sortOrder` | ``enum (`https://developers.google.com/workspace/admin/directory/reference/rest/v1/users/list#SortOrder`)`` Whether to return results in ascending or descending order, ignoring case. |
| `viewType` | ``enum (`https://developers.google.com/workspace/admin/directory/reference/rest/v1/users/list#ViewType`)`` Whether to fetch the administrator-only or domain-wide public view of the user. For more information, see [Retrieve a user as a non-administrator](https://developers.google.com/workspace/admin/directory/v1/guides/manage-users#retrieve_users_non_admin). |

### Request body

The request body must be empty.

### Response body

If successful, the response body contains data with the following structure:

| JSON representation |
|---|
| ``` { "kind": string, "trigger_event": string, "etag": string, "users": [ { object (`https://developers.google.com/workspace/admin/directory/reference/rest/v1/users#User`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `kind` | `string` Kind of resource this is. |
| `trigger_event` | `string` Event that triggered this response (only used in case of Push Response) |
| `etag` | `string` ETag of the resource. |
| `users[]` | ``object (`https://developers.google.com/workspace/admin/directory/reference/rest/v1/users#User`)`` A list of user objects. |
| `nextPageToken` | `string` Token used to access next page of this result. The page token is only valid for three days. |

### Authorization scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/admin.directory.user`
- `
  https://www.googleapis.com/auth/admin.directory.user.readonly`
- `
  https://www.googleapis.com/auth/cloud-platform`

For more information, see the [Authorization guide](https://developers.google.com/workspace/guides/configure-oauth-consent).

## Event

Type of the Subscription event

| Enums ||
|---|---|
| `ADD` | User Created Event |
| `DELETE` | User Deleted Event |
| `MAKE_ADMIN` | User Admin Status Change Event |
| `UNDELETE` | User Undeleted Event |
| `UPDATE` | User Updated Event |

## OrderBy

| Enums ||
|---|---|
| `EMAIL` | Primary email of the user. |
| `FAMILY_NAME` | User's family name. |
| `GIVEN_NAME` | User's given name. |

## Projection

| Enums ||
|---|---|
| `BASIC` | Do not include any custom fields for the user. |
| `CUSTOM` | Include custom fields from schemas requested in `customFieldMask`. |
| `FULL` | Include all fields associated with this user. |

## SortOrder

| Enums ||
|---|---|
| `ASCENDING` | Ascending order. |
| `DESCENDING` | Descending order. |

## ViewType

| Enums ||
|---|---|
| `admin_view` | Results include both administrator-only and domain-public fields for the user. |
| `domain_public` | Results only include fields for the user that are publicly visible to other users in the domain. |