PowerShell

How to Use the -Search Parameter with Get-MgGroup in Microsoft Graph PowerShell

The Get-MgGroup cmdlet allows Microsoft 365 administrators to retrieve directory groups including Microsoft 365 groups, security groups, and distribution lists. When you want to quickly locate groups based on partial matches in their name or description, the -Search parameter comes in handy.

This article explains how to correctly use -Search with Get-MgGroup, including working examples, syntax rules, and key considerations to avoid common errors.

Cmdlet Syntax

Get-MgGroup -Search '"property:value"' -ConsistencyLevel eventual -All

The -Search parameter must follow the property:value format and requires -ConsistencyLevel eventual.

Correct Examples Using -Search with Get-MgGroup

Example 1: Search Groups by Display Name (Exact or Partial Match)

Get-MgGroup -Search '"displayName:Marketing"' -ConsistencyLevel eventual -All

Returns all groups with "Marketing" in their display name, such as Marketing Team, Global Marketing, etc.

Example 2: Search Groups with a Multi-word Display Name

Get-MgGroup -Search '"displayName:Hello Team"' -ConsistencyLevel eventual -All

Finds groups named Hello Team or containing those words in the display name.

Example 3: Search Groups Based on Description

Get-MgGroup -Search '"description:Internal Project"' -ConsistencyLevel eventual -All

Returns all groups whose description includes the phrase Internal Project.

Example 4: Narrow Search and Display Custom Properties

Get-MgGroup -Search '"displayName:HR"' -ConsistencyLevel eventual -All -Property displayName, mail, id

Fetches only HR-related groups and limits the returned fields to Display Name, Mail, and ID.

Example 5: Export Matching Groups to CSV

Get-MgGroup -Search '"displayName:Project"' -ConsistencyLevel eventual -All |
Select-Object DisplayName, Description, Mail |
Export-Csv "ProjectGroups.csv" -NoTypeInformation

Searches for all project-related groups and exports them to a CSV file for reporting.

Example 6: Search Groups by Mail

Get-MgGroup -Search '"mail:allcompany@7xh7fj.onmicrosoft.com"' -ConsistencyLevel eventual -All

Searches for the group with mail address allcompany@7xh7fj.onmicrosoft.com and outputs the group details

Important Considerations When Using -Search

Use property:value Format

You must search using a supported property like displayName or description:

-Search '"displayName:Finance"' # ✅ Valid

-Search '"Finance"' # ❌ Invalid

Wrap Search String in Quotes

The entire property:value pair should be inside double quotes to be parsed correctly.

Use -ConsistencyLevel eventual

This is required for -Search to work with Graph API:

Get-MgGroup -Search '"displayName:Admin"' -ConsistencyLevel eventual -All

Supported Properties Are Limited

Currently, only displayName and description are searchable. Other fields like mail, mailNickname, or groupTypes do not work with -Search.

Search Is Case-Insensitive and Partial Match Friendly

There’s no need to match casing, and partial values like "displayName:Sales" will match Sales Team, Sales India, etc.

Common Errors and Fixes

Error Message	Cause	Solution
Clause 'Team Alpha' in $search is not of right format 'property:value'	Missing property: prefix	Use -Search '"displayName:Team Alpha"'
Request_UnsupportedQuery	Used unsupported field like mail or id	Only use displayName or description
-Search used without -ConsistencyLevel	Required parameter omitted	Always include -ConsistencyLevel eventual

🔎 -Search Works Only on Select Properties

The -Search parameter supports only specific fields like displayName and description.

Attempting to use it on unsupported fields will result in errors like "Search request is not supported for this resource."

📌 -Search vs -Filter — Know the Difference

Use -Search for broad keyword-based discovery, and -Filter when querying specific attributes like groupTypes or mailEnabled.

For exact matches or logic-based filtering, -Filter is the more appropriate choice.

Conclusion

The -Search parameter in Get-MgGroup is ideal for quick lookups based on group names or descriptions. Whether you're searching for Teams groups, project groups, or admin lists, using -Search with the right syntax and flags gives fast and relevant results.

Just remember:

Always use "property:value" format
Include -ConsistencyLevel eventual
Stick to supported fields like displayName and description

Graph PowerShell Explorer Widget

20 Graph PowerShell cmdlets with easily accessible "working" examples.

Permission Required

Example: