Use the Microsoft Search API to query data

Important

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

Using the Microsoft Search API, apps can query Office 365 data.

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

Common use cases

The 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 are executed on behalf of user. Search results are trimmed down to enforce any access control applied to the items. For example, in the context of files, permissions on the files will be evaluated part of the search request. Users cannot access more items in search than they would be able to 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 which is an integer that indicates the 0-based starting point to list search results on the page. The default value is 0.

  • size which is 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 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 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 3 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 names specified in stored_fields should be the retrievable Managed Property. These property names have been configured for the connection in the tenant administration of Microsoft Search.

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:

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.