search: query

Important

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

Runs the query specified in the request body. Search results are provided in the response.

Important

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.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Mail.Read, Files.Read.All, Calendars.Read, ExternalItem.Read.All
Delegated (personal Microsoft account) Not supported.
Application Not supported.

HTTP request

POST /search/query

Request headers

Name Description
Authorization Bearer {token}. Required.
Content-type application/json. Required.

Request body

In the request body, provide a JSON object with the following parameters.

Parameter Type Description
requests searchRequest collection The search request to be sent to the query endpoint formatted in a JSON blob. It contains the type of entities expected in the response, the underlying sources, the paging parameters, the requested fields, and the actual search query.

Response

If successful, this method returns HTTP 200 OK response code and a searchResponse collection object in the response body.

Common use cases

Examples

Request

The following is an example of the request.

POST https://graph.microsoft.com/beta/search/query
Content-type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "microsoft.graph.externalItem"
      ],
      "contentSources": [
        "/external/connections/connectionfriendlyname"
      ],
      "query": {
        "query_string": {
          "query": "contoso product"
        }
      },
      "from": 0,
      "size": 25,
      "stored_fields": [
        "title",
        "description"
      ]
    }
  ]
}

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
{
  "value": [
    {
      "searchTerms": [
        "searchTerms-value"
      ],
      "hitsContainers": [
        {
          "hits": [
            {
              "_id": "1",
              "_score": 1,
              "_sortField": "Relevance",
              "_summary": "_summary-value",
              "_source": "The source field will contain the underlying graph entity part of the response"
            }
          ],
          "total": 47,
          "moreResultsAvailable": true
        }
      ]
    }
  ]
}