Advanced hunting API

Applies to:

Note

For the full available Advanced Hunting API experience across all Microsoft Defenders' products, visit Use the Microsoft Graph security API - Microsoft Graph beta | Microsoft Learn.

Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.

Note

If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Tip

For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

Note

This API can only query tables belonging to Microsoft Defender for Endpoint. Tables belonging to other Microsoft 365 Defender services require the use of the Microsoft 365 Defender Advanced hunting API.

Limitations

  1. You can only run a query on data from the last 30 days.

  2. The results will include a maximum of 100,000 rows.

  3. The number of executions is limited per tenant:

    • API calls: Up to 45 calls per minute, up to 1500 calls per hour.
    • Execution time: 10 minutes of running time every hour and 3 hours of running time a day.
  4. The maximal execution time of a single request is 200 seconds.

  5. 429 response will represent reaching quota limit either by number of requests or by CPU. Read response body to understand what limit has been reached.

  6. The maximum query result size of a single request cannot exceed 124 MB. If exceeded, HTTP 400 Bad Request with the message "Query execution has exceeded the allowed result size. Optimize your query by limiting the number of results and try again" will appear.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs

Permission type Permission Permission display name
Application AdvancedQuery.Read.All 'Run advanced queries'
Delegated (work or school account) AdvancedQuery.Read 'Run advanced queries'

Note

When obtaining a token using user credentials:

  • The user needs to have 'View Data' AD role
  • The user needs to have access to the device, based on device group settings (See Create and manage device groups for more information)

Device group creation is supported in Defender for Endpoint Plan 1 and Plan 2.

HTTP request

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run

Request headers

Header Value
Authorization Bearer {token}. Required.
Content-Type application/json

Request body

In the request body, supply a JSON object with the following parameters:

Parameter Type Description
Query Text The query to run. Required.

Response

If successful, this method returns 200 OK, and QueryResponse object in the response body.

Example

Request example

Here is an example of the request.

POST https://api.securitycenter.microsoft.com/api/advancedqueries/run
{
    "Query":"DeviceProcessEvents
|where InitiatingProcessFileName =~ 'powershell.exe'
|where ProcessCommandLine contains 'appdata'
|project Timestamp, FileName, InitiatingProcessFileName, DeviceId
|limit 2"
}

Response example

Here is an example of the response.

Note

The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}