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 usesgRPC 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 whenprojection=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 ofdomain. You can also use themy_customer alias to represent your account'scustomerId. ThecustomerId is also returned as part of theUsers resource. You must provide either thecustomer or thedomain 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 thecustomer query parameter instead. Either thecustomer or thedomain 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, seeSearch for Users.

showDeleted

string

If set totrue, 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, seeRetrieve 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 theAuthorization guide.

Event

Type of the Subscription event

Enums
ADDUser Created Event
DELETEUser Deleted Event
MAKE_ADMINUser Admin Status Change Event
UNDELETEUser Undeleted Event
UPDATEUser Updated Event

OrderBy

Enums
EMAILPrimary email of the user.
FAMILY_NAMEUser's family name.
GIVEN_NAMEUser's given name.

Projection

Enums
BASICDo not include any custom fields for the user.
CUSTOMInclude custom fields from schemas requested incustomFieldMask.
FULLInclude all fields associated with this user.

SortOrder

Enums
ASCENDINGAscending order.
DESCENDINGDescending order.

ViewType

Enums
admin_viewResults include both administrator-only and domain-public fields for the user.
domain_publicResults only include fields for the user that are publicly visible to other users in the domain.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-03-25 UTC.