Use the $search query parameter in Microsoft Graph APIs

The $search query parameter is a powerful filtering mechanism in Microsoft Graph that enables you to find specific data by matching search criteria.

Support for this query parameter varies by entity. Some entities, like Microsoft Entra resources that derive from directoryObject, support $search only in advanced queries.

This article explains how to use the $search query parameter effectively with three key resource types: mail messages, people, and Microsoft Entra ID objects (directory objects). You learn the specific syntax requirements, supported properties, and search behaviors for each resource type.

Use $search on message collections

You can search messages based on specific message properties. Search results are sorted by the date and time the message was sent. A $search request returns up to 1,000 results.

When you search messages without specifying message properties, the search targets these default properties: from, subject, and body.

The following example returns all messages in the signed-in user's Inbox that contains "pizza" in any of the three default search properties:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"pizza\"";
});

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestSearch := "\"pizza\""

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.search = "\"pizza\"";
});

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.search('pizza')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"pizza\"";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Search '"pizza"'

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		search = "\"pizza\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Alternatively, you can search messages by specifying message property names that Keyword Query Language (KQL) syntax recognizes. These property names correspond to properties defined in the message entity of Microsoft Graph. Outlook and other Microsoft 365 applications like SharePoint support KQL syntax, which provides a common discovery domain for their data stores.

Searchable email property	Description	Example
attachment	Names of files attached to an email message.	GET `../me/messages?$search="attachment:api-catalog.md"`
bcc	The bcc field of an email message, specified as an SMTP address, display name, or alias.