Advanced hunting API
Applies to:
Warning
This advanced hunting API is an older version with limited capabilities. A more comprehensive version of the advanced hunting API that can query more tables is already available in the Microsoft Graph security API. See Advanced hunting using Microsoft Graph security API
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:
- us.api.security.microsoft.com
- eu.api.security.microsoft.com
- uk.api.security.microsoft.com
- au.api.security.microsoft.com
- swa.api.security.microsoft.com
- ina.api.security.microsoft.com
You can only run a query on data from the last 30 days.
The results include a maximum of 100,000 rows.
The number of executions is limited per tenant:
- API calls: Up to 45 calls per minute, and up to 1,500 calls per hour.
- Execution time: 10 minutes of running time every hour and 3 hours of running time a day.
The maximal execution time of a single request is 200 seconds.
429
response represents reaching quota limit either by number of requests or by CPU. Read response body to understand what limit was reached.The maximum query result size of a single request can't exceed 124 MB. If exceeded, an 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" occurs.
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 the
View Data
role assigned in Microsoft Entra ID - 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.
POST https://api.securitycenter.microsoft.com/api/advancedqueries/run
Header | Value |
---|---|
Authorization | Bearer {token}. Required. |
Content-Type | application/json |
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description |
---|---|---|
Query | Text | The query to run. Required. |
If successful, this method returns 200 OK, and QueryResponse object in the response body.
Here's 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"
}
Here's 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"
}
]
}
Tip
Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.