Use the Microsoft Search API to query data


APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.

You can use the Microsoft Search API to query Microsoft 365 data in your apps.

Search requests run in the context of the signed-in user, identified using an access token with delegated permissions.


Microsoft Graph connectors and Microsoft Search APIs (query and index) are currently in preview status. To use connectors with Microsoft Search or to build connectors, you must sign up for the connectors preview program. To join the preview program, submit the Microsoft Graph connectors preview sign-up form.

Common use cases

The Microsoft Search API provides a query method to search across your data in Microsoft Search. This section lists the common use cases, based on the properties you set in the query request body.

Search requests run on behalf of the user. Search results are scoped to enforce any access control applied to the items. For example, in the context of files, permissions on the files are evaluated as part of the search request. Users cannot access more items in a search than they can from the enumeration API.

Use cases Properties to define in the query request body
Scope search based on entity types entityTypes
Page results from and size
Get the most relevant emails enableTopResults
Get selected properties stored_fields
Use KQL in query terms query
Search external Files entityTypes
Search within a specific contentSource (indexing API) contentSources

Scope search based on entity types

Define the scope of the search request using the entityTypes property in the query request payload. The following are the supported entity types:

Page search results

Control pagination of the search results by specifying the following two properties in the query request body:

  • from - An integer that indicates the 0-based starting point to list search results on the page. The default value is 0.

  • size - An integer that indicates the number of results to be returned for a page. The default value is 25.

Note the following limits if you're searching the event or message entity:

  • from must start at zero in the first page request; otherwise, the request results in an HTTP 400 Bad request.
  • The maximum results per page (size) is 200.
  • The maximum total number of items that can be returned by paginating is 1000.
  • Going beyond the limits returns a best effort response. The request does not result in an HTTP 400.

Best practices:

  • Specify a smaller first page in the initial request. For example, specify from as 0, size as 25.

  • Paginate subsequent pages by updating the from and size properties. You can increase the page size in each subsequent request. The following table shows an example.

    Page from size
    1 0 25
    2 25 50
    3 75 75
    4 150 100

Get the most relevant emails

When searching the message entity, specifying enableTopResults as true returns a hybrid list of messages: the first three messages in the response are sorted by relevance; the remaining messages are sorted by date.

Get selected properties

When searching an externalItem entity, use the stored_fields property to specify the fields to be returned in the response.

The fields specified in stored_fields should be retrievable managed properties that have been configured for the connection via the Microsoft Search tenant administration.

Keyword Query Language (KQL) support

Specify free text keywords, operators (such as AND, OR), and property restrictions in KQL syntax in the actual search query string (query property of the query request body). The syntax and command depend on the entity types (in the entityTypes property) you target in the same query request body.

Depending on the entity type, the searchable properties vary. For details, see:

Error handling

The search API returns error responses as defined by OData error object definition, each of which is a JSON object containing a code and a message.

Known limitations

The search API has the following limitations:

  • The query method is defined to allow passing a collection of one or more searchRequest instances at once. However, the service currently supports only a single searchRequest at a time.

  • The searchRequest resource supports passing multiple types of entities at a time. However, currently the only supported combination is driveItem and externalFile. Other combinations are invalid.

  • The contentSource property, which defines the connection to use, is only applicable when entityType is specified as externalItem.

  • The search API does not support custom sort and always sorts results in the following ways:

    • Sort message or event type results by date.

    • Sort driveItem, externalFile, or externalItem type results by relevance.

What's new

Find out about the latest new features and updates for this API set.