`client.alerts`¶

Work with alerts and alert-related entities.

Property¶

client.alerts

Methods¶

get_all(query: AlertsQuery | None = None) -> AlertsResults: list alerts with optional filtering.
get(id: str) -> AlertsResults: fetch one alert by ID.
domains(id: str) -> DomainResults: fetch domains related to an alert.
files(id: str) -> FileResults: fetch files related to an alert.
ips(id: str) -> IPResults: fetch IPs related to an alert.
machines(id: str) -> MachineResults: fetch machines related to an alert.
user(id: str) -> UserResults: fetch the user related to an alert.
createAlertByReference(payload) -> AlertsResults: create an alert by reference and return the created alert wrapper.
batchUpdate(payload) -> bool: batch-update alerts and return success as a boolean.
update(payload) -> AlertsResults: update a single alert and return the updated alert wrapper.

Notes¶

get_all() uses AlertsQuery, which inherits the shared pagination fields.
batchUpdate() is one of the endpoints that returns a success boolean instead of a results wrapper.
update() is separate from batchUpdate() and targets a single alert ID.

API¶

Microsoft Defender for Endpoint alerts endpoint models and client surface.

This module defines: - AlertsQuery, AlertCreateQuery, and AlertUpdateQuery request models. - *Results wrappers mapped to Arrow schemas for alerts and related entities. - AlertsEndpoint methods for retrieving alerts and related domains, files, IPs, machines, and users.

Most endpoint methods return lazy BaseResults subclasses and defer HTTP requests until a terminal materialization method is called.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/alerts

AlertsQuery ¶

Query parameters for the /api/alerts endpoint.

Example:

    query = AlertsQuery(severity="Medium", pageSize=500)
    query = AlertsQuery(severity=["Medium", "High"], pageSize=500)

AlertCreateQuery ¶

Query parameters for creating an alert by reference. All fields are required.

Example:

    query = AlertCreateQuery(referenceId="12345", referenceType="CustomReference" ... , category="Malware")

model_post_init ¶

model_post_init(__context: Any) -> None

Validate that the category is not 'Unknown' because alert creation does not allow 'Unknown' category.

UpdateAlertPayload ¶

Payload for updating a single alert using one alert ID.

AlertsResults ¶

AlertsResults(
    endpoint: BaseEndpoint,
    params: dict[str, str],
    *,
    path: str | None = None,
    single: bool = False,
    files: bool = False,
    method: str = "GET",
    request_kwargs: dict[str, Any] | None = None,
    use_concurrent_skip_pagination: bool | None = None,
    skip_page_size: int | None = None,
    skip_max_concurrent: int | None = None,
)

Results from the /api/alerts endpoint.

AlertsEndpoint ¶

AlertsEndpoint(http: Client, auth: MSALAuth)

Client for the /api/alerts endpoint.

Methods:

Name	Description
`- get_all`	Get all alerts matching the query parameters.
`- get`	Get a single alert by ID.
`- domains`	Get the domains associated with an alert.
`- files`	Get the files associated with an alert.
`- ips`	Get the IPs associated with an alert.
`- machines`	Get the machines associated with an alert.
`- user`	Get the user associated with an alert.
`- createAlertByReference`	Create an alert by reference.
`- batchUpdate`	Batch update alerts.
`- update`	Update alerts (alias for batch update).

get_all ¶

get_all(query: AlertsQuery | None = None) -> AlertsResults

Get all alerts matching the query parameters.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alerts

get ¶

get(id: str) -> AlertsResults

Get a single alert by ID.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alert-info-by-id

domains ¶

domains(id: str) -> DomainResults

Get the domains associated with an alert.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alert-related-domain-info

files ¶

files(id: str) -> FileResults

Get the files associated with an alert.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alert-related-files-info

ips ¶

ips(id: str) -> IPResults

Get the IPs associated with an alert.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alert-related-ip-info

machines ¶

machines(id: str) -> MachineResults

Get the machines associated with an alert.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alert-related-machine-info

user ¶

user(id: str) -> UserResults

Get the user associated with an alert.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-alert-related-user-info

createAlertByReference ¶

createAlertByReference(
    payload: CreateAlertByReferencePayload,
) -> AlertsResults

Create alert

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/create-alert-by-reference

batchUpdate ¶

batchUpdate(payload: BatchUpdateAlertPayload) -> bool

Batch update alerts

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/batch-update-alerts - If successful, this method returns 200 OK, with an empty response body.

update ¶

update(payload: UpdateAlertPayload) -> AlertsResults

Update alerts (alias for batch update)

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/update-alert

client.alerts¶