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 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 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 (Event)

Event on which subscription is intended (if subscribing)
maxResults

integer

Maximum number of results to return.
orderBy

enum (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 (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.
showDeleted

string

If set to true, retrieves the list of deleted users. (Default: false)
sortOrder

enum (SortOrder)

Whether to return results in ascending or descending order, ignoring case.
viewType

enum (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.

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 (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 (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.

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.