Stay organized with collections
Save and categorize content based on your preferences.
You can search for groups matching certain attributes with the
groups.list method of the
Directory API. This method accepts the query parameter which is a search
query combining one or more search clauses. Each search clause is made up of
three parts:
Field
Group attribute that is searched. For example, name.
Operator
Test that is performed on the data to provide a match. For example, the =
operator tests if a text attribute matches a value.
Value
The content of the attribute that is tested. For example, groupName.
Multiple clauses are separated by whitespace and are implicitly joined by an
AND operator.
Fields
Field
Value Type
Operators
Description
email
string
=, :{PREFIX}*
The group's email address. Note: This cannot be used with the memberKey parameter in the same query.
name
string
=, :{PREFIX}*
The group's display name. Note: This cannot be used with memberKey parameter in the same query.
memberKey
string
=,
The memberKey query parameter returns all groups for which a user or group has a membership. This value can be any of the user's primary or alias email address, a group's primary or alias email address, or a user's unique ID. Note: This cannot be used along with the email or name parameters in the same query.
Value Types
Value Type
Notes
string
Surround with single quotes ' if the query contains whitespace. Escape single quotes in queries with \', for example 'Valentine\'s Day'.
Operators
Operator
Supported Value Types
Notes
=
string, boolean, number, date
The field and the value match exactly. For example, name=contact matches all groups with the name attribute "contact", but not "contactgroup". Supported on most string fields (see above).
:{PREFIX}*
string
The field starts with the value. For example, a query with email:support* matches groups with email values of "supportgroup@", and "support@" but not "contactsupport". Only supported on a limited set of string fields (see above).
Examples
All queries use the groups.list
method, which has an HTTP request similar to the following (line breaks included for readability):
GET https://admin.googleapis.com/admin/directory/v1/groups
?domain=primary domain
&query=query parameters
The query parameters must be URL encoded. For example, the query
query=email:support* is URL encoded as query=email%3Asupport*.
All examples on this page show unencoded query parameters.
Client libraries handle this URL encoding automatically.
Search for a group by display name
name='contact'
Search for groups matching an email prefix
email:admin*
Search for all groups of a user
memberKey=user@company.com
Search for groups with name and email starting with contact
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-04 UTC."],[],[],null,["You can search for groups matching certain attributes with the\n[`groups.list`](/workspace/admin/directory/v1/reference/groups/list) method of the\nDirectory API. This method accepts the `query` parameter which is a search\nquery combining one or more search clauses. Each search clause is made up of\nthree parts:\n\nField\n: Group attribute that is searched. For example, `name`.\n\nOperator\n: Test that is performed on the data to provide a match. For example, the `=`\n operator tests if a text attribute *matches* a value.\n\nValue\n: The content of the attribute that is tested. For example, `groupName`.\n\nMultiple clauses are separated by whitespace and are implicitly joined by an\n`AND` operator.\n| **Note:** Most group data updates within 1 hour, however, it may take up to 36 hours for new data to be reflected in all search results.\n\nFields\n\n| Field | Value Type | Operators | Description |\n|-------------|------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `email` | string | `=`, `:{PREFIX}*` | The group's email address. Note: This cannot be used with the `memberKey` parameter in the same query. |\n| `name` | string | `=`, `:{PREFIX}*` | The group's display name. Note: This cannot be used with `memberKey` parameter in the same query. |\n| `memberKey` | string | `=`, | The `memberKey` query parameter returns all groups for which a user or group has a membership. This value can be any of the user's primary or alias email address, a group's primary or alias email address, or a user's unique ID. Note: This cannot be used along with the `email` or `name` parameters in the same query. |\n\nValue Types\n\n| Value Type | Notes |\n|------------|------------------------------------------------------------------------------------------------------------------------------------------------|\n| string | Surround with single quotes `'` if the query contains whitespace. Escape single quotes in queries with `\\'`, for example `'Valentine\\'s Day'`. |\n\nOperators\n\n| Operator | Supported Value Types | Notes |\n|--------------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `=` | string, boolean, number, date | The field and the value match exactly. For example, `name=contact` matches all groups with the `name` attribute `\"contact\"`, but not `\"contactgroup\"`. Supported on most string fields ([see above](#fields)). |\n| `:{PREFIX}*` | string | The field starts with the value. For example, a query with `email:support*` matches groups with `email` values of `\"supportgroup@\"`, and `\"support@\"` but not `\"contactsupport\"`. Only supported on a limited set of string fields ([see above](#fields)). |\n\nExamples\n\nAll queries use the [`groups.list`](/workspace/admin/directory/v1/reference/groups/list)\nmethod, which has an HTTP request similar to the following (line breaks included for readability): \n\n```\nGET https://admin.googleapis.com/admin/directory/v1/groups\n?domain=primary domain\n&query=query parameters\n```\n\nThe `query` parameters must be URL encoded. For example, the query\n`query=email:support*` is URL encoded as `query=email%3Asupport*`.\nAll examples on this page show unencoded `query` parameters.\nClient libraries handle this URL encoding automatically.\n\nSearch for a group by display name \n\n name='contact'\n\nSearch for groups matching an email prefix \n\n email:admin*\n\nSearch for all groups of a user \n\n memberKey=user@company.com\n\nSearch for groups with name and email starting with contact \n\n name:contact* email:contact*"]]
