Use the Microsoft Graph security API
The Microsoft Graph security API provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. This empowers customers to streamline security operations and better defend against increasing cyber threats. The Microsoft Graph security API federates queries to all onboarded security providers and aggregates responses. Use the Microsoft Graph security API to build applications that:
- Consolidate and correlate security alerts from multiple sources.
- Pull and investigate all incidents and alerts from services that are part of or integrated with Microsoft 365 Defender.
- Unlock contextual data to inform investigations.
- Automate security tasks, business processes, workflows, and reporting.
- Send threat indicators to Microsoft products for customized detections.
- Invoke actions to in response to new threats.
- Provide visibility into security data to enable proactive risk management.
The Microsoft Graph security API provides key features as described in the following sections.
Advanced hunting
Advanced hunting is a query-based threat hunting tool that lets you explore up to 30 days of raw data. You can proactively inspect events in your network to locate threat indicators and entities. The flexible access to data enables unconstrained hunting for both known and potential threats.
Use runHuntingQuery to run a Kusto Query Language (KQL) query on data stored in Microsoft 365 Defender. Use the returned result set to enrich an existing investigation or to uncover undetected threats in your network.
Quotas and resource allocation
The following conditions relate to all queries.
- Queries explore and return data from the past 30 days.
- Results can return up to 100,000 rows.
- You can make up to at least 45 calls per minute per tenant. The number of calls varies per tenant based on its size.
- Each tenant is allocated CPU resources, based on the tenant size. Queries are blocked if the tenant reaches 100% of the allocated resources until after the next 15-minute cycle. To avoid blocked queries due to excess consumption, follow the guidance in Optimize your queries to avoid hitting CPU quotas.
- If a single request runs for more than three minutes, it times out and returns an error.
- A
429HTTP response code indicates that you reached the allocated CPU resources, either by number of requests sent, or by allotted running time. Read the response body to understand the limit you reached.
Alerts
Alerts are detailed warnings about suspicious activities in a customer's tenant that Microsoft or partner security providers identified and flagged for action. Attacks typically employ various techniques against different types of entities, such as devices, users, and mailboxes. The result is alerts from multiple security providers for multiple entities in the tenant. Piecing the individual alerts together to gain insight into an attack can be challenging and time-consuming.
The security API offers two types of alerts that aggregate other alerts from security providers and make analyzing attacks and determining response easier:
- Alerts and incidents - these are the latest generation of alerts in the Microsoft Graph security API. They're represented by the alert resource and its collection, incident resource, defined in the
microsoft.graph.securitynamespace. - Legacy alerts - these are the first generation of alerts in the Microsoft Graph security API. They're represented by the alert resource defined in the
microsoft.graphnamespace.
Alerts and incidents
These alert resources first pull alert data from security provider services, that are either part of or integrated with Microsoft 365 Defender. Then they consume the data to return rich, valuable clues about a completed or ongoing attack, the impacted assets, and associated evidence. In addition, they automatically correlate other alerts with the same attack techniques or the same attacker into an incident to provide a broader context of an attack. They recommend response and remediation actions, offering consistent actionability across all the different providers. The rich content makes it easier for analysts to collectively investigate and respond to threats.
Alerts from the following security providers are available via these rich alerts and incidents:
- Microsoft Entra ID Protection
- Microsoft 365 Defender
- Microsoft Defender for Cloud Apps
- Microsoft Defender for Endpoint
- Microsoft Defender for Identity
- Microsoft Defender for Office 365
- Microsoft Purview Data Loss Prevention
Legacy alerts
Note
The legacy alerts API is deprecated and will be removed by April 2026. We recommend that you migrate to the new alerts and incidents API.
The legacy alert resources federate calling of supported Azure and Microsoft 365 Defender security providers. They aggregate common alert data among the different domains to allow applications to unify and streamline management of security issues across all integrated solutions. They enable applications to correlate alerts and context to improve threat protection and response.
The legacy version of the security API offers the alert resource that federates calling of supported Azure and Microsoft 365 Defender security providers. This alert resource aggregates alert data that’s common among the different domains to allow applications to unify and streamline management of security issues across all integrated solutions. This enables applications to correlate alerts and context to improve threat protection and response.
With the alert update capability, you can sync the status of specific alerts across different security products and services that are integrated with the Microsoft Graph security API by updating your alert entity.
Alerts from the following providers are available via the alert resource. Support for GET alerts, PATCH alerts, and subscribe (via webhooks) is indicated in the following table.
| Security provider | GET alert |
PATCH alert |
Subscribe to alert |
|---|---|---|---|
| Microsoft Entra ID Protection | ✓ |
✓ |
|
Microsoft 365
|
✓ |
||
| Microsoft Defender for Cloud Apps | ✓ |
✓ |
|
| Microsoft Defender for Endpoint ** | ✓ |
✓ |
|
| Microsoft Defender for Identity *** | ✓ |
✓ |
|
| Microsoft Sentinel (formerly Azure Sentinel) | ✓ |
Not supported in Microsoft Sentinel |
✓ |
Note: New providers are continuously onboarding to the Microsoft Graph security ecosystem. To request new providers or for extended support from existing providers, file an issue in the Microsoft Graph security GitHub repo.
* File issue: Alert status gets updated across Microsoft Graph security API integrated applications but not reflected in the provider’s management experience.
** Microsoft Defender for Endpoint requires additional user roles to those required by the Microsoft Graph security API. Only the users in both Microsoft Defender for Endpoint and Microsoft Graph security API roles can access the Microsoft Defender for Endpoint data. Because application-only authentication isn't limited by this, we recommend that you use an application-only authentication token.
*** Microsoft Defender for Identity alerts are available via the Microsoft Defender for Cloud Apps integration. This means you get Microsoft Defender for Identity alerts only if you joined Unified SecOps and connected Microsoft Defender for Identity into Microsoft Defender for Cloud Apps. Learn more about how to integrate Microsoft Defender for Identity and Microsoft Defender for Cloud Apps.
Attack simulation and training
Attack simulation and training is part of Microsoft Defender for Office 365. This service lets users in a tenant experience a realistic benign phishing attack and learn from it. Social engineering simulation and training experiences for end users help reduce the risk of users being breached via those attack techniques. The attack simulation and training API enables tenant administrators to view launched simulation exercises and trainings, and get reports on derived insights into online behaviors of users in the phishing simulations.
eDiscovery
Microsoft Purview eDiscovery (Premium) provides an end-to-end workflow to preserve, collect, analyze, review, and export content that's responsive to your organization's internal and external investigations.
Identities
Health issues
The Microsoft Defender for Identity health issues API allows you to monitor the health status of your sensors and agents across your hybrid identity infrastructure. You can use the health issues API to retrieve information about the current health issues of your sensors, such as the issue type, status, configuration, and severity. You can also use this API to identify and resolve any issues that might affect the functionality or security of your sensors and agents.
Note: The Microsoft Defender for Identity health issues API is only available on the Defender for Identity plan or Microsoft 365 E5/A5/G5/F5 Security service plans.
Sensors
The Defender for Identity sensors management API allows you to create detailed reports of the sensors in your workspace, including information about the server name, sensor version, type, state, and health status. It also enables you to manage sensor settings, such as adding descriptions, enabling or disabling delayed updates, and specifying the domain controller that the sensor connects to for querying Entra ID.
Incidents
An incident is a collection of correlated alerts and associated data that make up the story of an attack. Incident management is part of Microsoft 365 Defender, and is available in the Microsoft 365 Defender portal (https://security.microsoft.com/).
Microsoft 365 services and apps create alerts when they detect a suspicious or malicious event or activity. Individual alerts provide valuable clues about a completed or ongoing attack. However, attacks typically employ various techniques against different types of entities, such as devices, users, and mailboxes. The result is multiple alerts for multiple entities in your tenant.
Because piecing the individual alerts together to gain insight into an attack can be challenging and time-consuming, Microsoft 365 Defender automatically aggregates the alerts and their associated information into an incident.
Grouping related alerts into an incident gives you a comprehensive view of an attack. For example, you can see:
- Where the attack started.
- What tactics were used.
- How far the attack went into your tenant.
- The scope of the attack, such as how many devices, users, and mailboxes were impacted.
- All of the data associated with the attack.
The incident resource and its APIs allow you to sort through incidents to create an informed cyber security response. It exposes a collection of incidents, with their related alerts, that were flagged in your network, within the time range you specified in your environment retention policy.
Information protection
The Microsoft Graph threat assessment API helps organizations to assess the threat received by any user in a tenant. This empowers customers to report spam emails, phishing URLs, or malware attachments they receive to Microsoft. The policy check result and rescan result can help tenant administrators understand the threat scanning verdict and adjust their organizational policy.
Records management
Most organizations need to manage data to proactively comply with industry regulations and internal policies, reduce risk in the event of litigation or a security breach, and let people effectively and agilely share knowledge that is current and relevant to them. You can use the records management APIs to systematically apply retention labels to different types of content that require different retention settings. For example, you can configure the start of retention period from when the content was created, last modified, labeled or when an event occurs for a particular event type. Further, you can use file plan descriptors to improve the manageability of these retention labels.
Secure Score
Microsoft Secure Score is a security analytics solution that gives you visibility into your security portfolio and how to improve it. With a single score, you can better understand what you did to reduce your risk in Microsoft solutions. You can also compare your score with other organizations and see how your score has been trending over time. The Microsoft Graph security secureScore and secureScoreControlProfile entities help you balance your organization's security and productivity needs while enabling the appropriate mix of security features. You can also project what your score would be after you adopt security features.
Threat intelligence
Microsoft Defender Threat Intelligence delivers world-class threat intelligence to help protect your organization from modern cyber threats. You can use Threat Intelligence to identify adversaries and their operations, accelerate detection and remediation, and enhance your security investments and workflows.
The threat intelligence APIs allow you to operationalize intelligence found within the user interface. This includes finished intelligence in the forms of articles and intel profiles, machine intelligence such as IoCs and reputation verdicts, and enrichment data such as passive DNS, cookies, components, and trackers.
Common use cases
The following are some of the most popular requests for working with the Microsoft Graph security API.
You can use Microsoft Graph webhooks to subscribe to and receive notifications about updates to Microsoft Graph security entities.
Resources
Code and contribute to these Microsoft Graph security API samples:
Engage with the community:
Next steps
The Microsoft Graph security API can open up new ways for you to engage with different security solutions from Microsoft and partners. Follow these steps to get started:
- Drill down into alerts, secureScore, and secureScoreControlProfiles.
- Try the API in the Graph Explorer. Under Sample Queries, choose show more samples and set the Security category to on.
- Try subscribing to and receiving notifications on entity changes.
Related content
Code and contribute to this Microsoft Graph security API sample:
Explore other options to connect with the Microsoft Graph security API:
Engage with the community: