Important
The improved Microsoft 365 Defender portal is now available. This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 Defender portal. Learn what’s new.
Applies to:
Important
Some information relates to prereleased product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
An incident is a collection of related alerts that help describe an attack. Events from different entities in your organization are automatically aggregated by Microsoft 365 Defender. You can use the incidents API to programatically access your organization’s incidents and related alerts.
Quotas and resource allocation
You can request up to 50 calls per minute or 1500 calls per hour. Each method also has its own quotas. For more information on method-specific quotas, see the respective article for the method you want to use.
A 429 HTTP response code indicates that you’ve reached a quota, either by number of requests sent, or by allotted running time. The response body will include the time until the quota you reached will be reset.
Permissions
The incidents API requires different kinds of permissions for each of its methods. For more information about required permissions, see the respective method’s article.
Methods
| Method | Return Type | Description |
|---|---|---|
| List incidents | Incident list | Get a list of incidents. |
| Update incident | Incident | Update a specific incident. |
| Get incident | Incident | Get a single incident. |
Request body, response, and examples
Refer to the respective method articles for more details on how to construct a request or parse a response, and for practical examples.
Common properties
| Property | Type | Description |
|---|---|---|
| incidentId | long | Incident unique ID. |
| redirectIncidentId | nullable long | The Incident ID the current Incident was merged to. |
| incidentName | string | The name of the Incident. |
| createdTime | DateTimeOffset | The date and time (in UTC) the Incident was created. |
| lastUpdateTime | DateTimeOffset | The date and time (in UTC) the Incident was last updated. |
| assignedTo | string | Owner of the Incident. |
| severity | Enum | Severity of the Incident. Possible values are: UnSpecified, Informational, Low, Medium, and High. |
| status | Enum | Specifies the current status of the incident. Possible values are: Active, InProgress, Resolved, and Redirected. |
| classification | Enum | Specification of the incident. Possible values are: Unknown, FalsePositive, TruePositive. |
| determination | Enum | Specifies the determination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, Other. |
| tags | string List | List of Incident tags. |
| comments | List of incident comments | Incident Comment object contains: comment string, createdBy string, and createTime date time. |
| alerts | Alert List | List of related alerts. See examples at List incidents API documentation. |