`client.machines`¶

Access machine inventory and machine-scoped related resources.

Property¶

client.machines

Methods¶

get_all(query: MachinesQuery | None = None) -> MachineResults: list machines with optional filtering.
bigPageSize() -> MachineResults: list machines through the large-page endpoint.
get(id: str) -> MachineResults: fetch one machine by ID.
logonusers(id: str) -> UserResults: fetch machine logon users.
alerts(id: str) -> AlertsResults: fetch alerts related to a machine.
software(id: str) -> SoftwareResults: fetch installed software for a machine.
vulnerabilities(id: str) -> VulnerabilityDTOResults: fetch vulnerabilities for a machine.
recommendations(id: str) -> RecommendationResults: fetch recommendations for a machine.
getmissingkbs(id: str) -> ProductDTOResults: fetch missing KBs for a machine.
findbyip(ip: str, timestamp: datetime) -> MachineResults: find machines by internal IP and timestamp.
tags(id: str, payload: TagsPayload) -> Response: submit a machine tag request and return the raw response.
findbytag(tag: str, useStartsWithFilter: bool = False) -> MachineResults: find machines by tag.
unTaggedMachines() -> MachineResults: fetch untagged machines.
addOrRemoveTagForMultipleMachines(payload: AddOrRemoveTagForMultipleMachinesPayload) -> MachineResults: add or remove a tag across multiple machines.
dlp() -> DlpMachineResults: fetch Data Loss Prevention machine events.
logsCollection(id: str, payload: LogsCollectionPayload) -> Response: submit a logs collection request for a machine.
runCustomPlaybook(id: str, payload: RunCustomPlaybookPayload) -> Response: run a custom playbook on a machine.
setDeviceValue(id: str, payload: SetDeviceValuePayload) -> Response: set a device value for a machine.
setExclusion(id: str, payload: SetExclusionPayload) -> Response: set an exclusion for a machine.

Notes¶

get_all() auto-paginates unless top or skip is set in MachinesQuery.
findbyip() normalizes timestamps to UTC before constructing the request path.
Methods returning Response expose raw httpx.Response objects because their response schemas are currently unknown.
This endpoint also contains private helper methods that power public export-backed endpoints such as browser_extension, certificate_inventory, device_av_health, investigations, machine_actions, and baseline_configurations.

API¶

Microsoft Defender for Endpoint machines endpoint models and client surface.

This module defines: - MachinesQuery: an OData-style query model for filtering machine listings. - *Results wrappers: lazy result containers bound to Arrow schemas. - MachinesEndpoint: endpoint methods for machine retrieval and related resources, including logon users, alerts, software, vulnerabilities, recommendations, missing KBs, and lookup helpers (findbyip, tag).

Endpoint methods return lazy BaseResults subclasses and do not issue HTTP requests until a terminal materialization method is called.

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

MachinesQuery ¶

Query parameters for the /api/machines endpoint.

All fields are optional — omitted fields are simply not sent. Pydantic enforces the constraints (ge/le) at construction time, so invalid values are caught before hitting the wire.

Example:

query = MachinesQuery(healthStatus="Active", pageSize=500)
query = MachinesQuery(exposureLevel=["Medium", "High"], pageSize=500)

MachinesExportQuery ¶

Query parameters for machines export endpoints.

See MachinesEndpoint._baselineComplianceAssessmentExport for an example of usage.

AssetBaselineAssessmentResults ¶

AssetBaselineAssessmentResults(
    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/machines/{id}/BaselineComplianceAssessmentByMachine endpoint.

MachineReferencesResults ¶

MachineReferencesResults(
    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/recommendations/{id}/machinereferences endpoint.

MachineResults ¶

MachineResults(
    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/machines endpoint.

DlpMachineResults ¶

DlpMachineResults(
    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/machines/dlp endpoint.

MachinesEndpoint ¶

MachinesEndpoint(http: Client, auth: MSALAuth)

Client for the /api/machines endpoint. This is not intended to be used directly. Instead, used through MDEClient.machines.

Returns a lazy MachineResults handle, no HTTP request is issued until a terminal method is called::

    results = client.machines.get_all(query)
    records = results.to_json()      # list[dict]
    table   = results.to_arrow()     # pa.Table  (requires [arrow])
    df      = results.to_polars()    # DataFrame (requires [polars])

**Call ``results.refresh()`` to discard cached data and re-fetch.**

get_all ¶

get_all(
    query: MachinesQuery | None = None,
) -> MachineResults

Get all machines, with optional filtering.

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

bigPageSize ¶

bigPageSize() -> MachineResults

Get all machines with a big page size, with optional filtering.

This method is identical to get_all but sets the page size to 200,000 (the maximum allowed) to reduce the number of requests needed for larger data sets.

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

get ¶

get(id: str) -> MachineResults

Get machine by ID

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

logonusers ¶

logonusers(id: str) -> UserResults

Get machine logon users for a machine

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-machine-log-on-users

alerts ¶

alerts(id: str) -> AlertsResults

Get machine related alerts

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

software ¶

software(id: str) -> SoftwareResults

Get installed software

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

vulnerabilities ¶

vulnerabilities(id: str) -> VulnerabilityDTOResults

Get discovered vulnerabilities for a machine.

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

recommendations ¶

recommendations(id: str) -> RecommendationResults

Get security recommendations for a machine.

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

getmissingkbs ¶

getmissingkbs(id: str) -> ProductDTOResults

Get missing KBs by device ID

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/get-missing-kbs-machine

findbyip ¶

findbyip(
    ip: str, timestamp: datetime | str
) -> MachineResults

Find devices by internal IP

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/find-machines-by-ip

Parameters:

Name	Type	Description	Default
`ip`	`str`	The internal IP address to search for.	required
`timestamp`	`datetime \| str`	UTC ISO 8601 timestamp to search for.	required

tags ¶

tags(id: str, payload: TagsPayload) -> Response

Get tags for a machine

Note: Unknown results for this endpoint and will return httpx.Response object directly. If you figure out what schema it returns, please log an issue or submit a PR to update the return type and parse the response accordingly. You also need to have this enabled on your tenant for it to work

Docs: Null (undocumented endpoint)

findbytag ¶

findbytag(
    tag: str, useStartsWithFilter: bool = False
) -> MachineResults

Find devices by tag API

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/find-machines-by-tag

Parameters:

Name	Type	Description	Default
`tag`	`str`	The tag to search for. Can be a full tag or a prefix if useStartsWithFilter is true.	required
`useStartsWithFilter`	`bool`	Whether to use startswith filter or exact match. Default is false (exact match).	`False`

unTaggedMachines ¶

unTaggedMachines() -> MachineResults

Get untagged machines

Docs: Null (undocumented endpoint)

addOrRemoveTagForMultipleMachines ¶

addOrRemoveTagForMultipleMachines(
    payload: AddOrRemoveTagForMultipleMachinesPayload,
) -> MachineResults

Add or remove a tag for multiple machines

Docs: Null (undocumented endpoint)

dlp ¶

dlp() -> DlpMachineResults

Get Data Loss Prevention (DLP) events for a machine.

Docs: Null (undocumented endpoint)

logsCollection ¶

logsCollection(
    id: str, payload: LogsCollectionPayload
) -> Response

Get logs collection for a machine.

Note: Unknown results for this endpoint and will return httpx.Response object directly. If you figure out what schema it returns, please log an issue or submit a PR to update the return type and parse the response accordingly. You also need to have this enabled on your tenant for it to work

Docs: Null (undocumented endpoint)

runCustomPlaybook ¶

runCustomPlaybook(
    id: str, payload: RunCustomPlaybookPayload
) -> Response

Run a custom playbook on a machine.

Note: The response schema for this endpoint is currently unknown. This method will return the raw httpx.Response object. If you have information on the response schema, please log an issue or submit a PR to update the return type and parse the response accordingly.

Docs: Null (undocumented endpoint)

setDeviceValue ¶

setDeviceValue(
    id: str, payload: SetDeviceValuePayload
) -> Response

Set device value for a machine.

Note: The response schema for this endpoint is currently unknown. This method will return the raw httpx.Response object. If you have information on the response schema, please log an issue or submit a PR to update the return type and parse the response accordingly.

Docs: Null (undocumented endpoint)

setExclusion ¶

setExclusion(
    id: str, payload: SetExclusionPayload
) -> Response

Set exclusion for a machine.

Note: The response schema for this endpoint is currently unknown. This method will return the raw httpx.Response object. If you have information on the response schema, please log an issue or submit a PR to update the return type and parse the response accordingly.

Docs: Null (undocumented endpoint)

client.machines¶

Property¶

Methods¶

Notes¶

API¶

MachinesQuery ¶

MachinesExportQuery ¶

AssetBaselineAssessmentResults ¶

MachineReferencesResults ¶

MachineResults ¶

DlpMachineResults ¶

MachinesEndpoint ¶

get_all ¶

bigPageSize ¶

get ¶

logonusers ¶

alerts ¶

software ¶

vulnerabilities ¶

recommendations ¶

getmissingkbs ¶

findbyip ¶

tags ¶

findbytag ¶

unTaggedMachines ¶

addOrRemoveTagForMultipleMachines ¶

dlp ¶

logsCollection ¶

runCustomPlaybook ¶

setDeviceValue ¶

setExclusion ¶

`client.machines`¶