List MachineActions API

Applies to: Microsoft Defender for Endpoint Plan 1, Microsoft Defender for Endpoint Plan 2

API description

Retrieves a collection of Machine Actions.

Supports OData V4 queries. OData supported operators:

$filter on the following properties:
- id
- status
- machineId
- type
- requestor
- creationDateTimeUtc
$stop with max value of 10,000.
$skip

See examples at OData queries with Microsoft Defender for Endpoint.

Limitations

Maximum page size is 10,000.
Rate limitations for this API are 100 calls per minute and 1,500 calls per hour.

Permissions

When obtaining a token using user credentials:

The user needs to have at least the following role permission: 'View Data'. For more information, see: Create and manage roles.

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	Machine.ReadWrite.All	'Read and write all machine information'
Delegated (work or school account)	Machine.ReadWrite	'Read and write machine information'

HTTP request

GET https://api.security.microsoft.com/api/machineactions

Request headers

Name	Type	Description
Authorization	String	Bearer {token}. Required.

Request body

Empty

Response

If successful, this method returns 200, Ok response code with a collection of machineAction entities.

Example 1

Example 1 request

Here's an example of the request on an organization that has three MachineActions.

GET https://api.security.microsoft.com/api/machineactions

Example 1 response

Here's an example of the response.

HTTP/1.1 200 Ok
Content-type: application/json
{
    "@odata.context": "https://api.security.microsoft.com/api/$metadata#MachineActions",
    "value": [
        {
            "id": "69dc3630-1ccc-4342-acf3-35286eec741d",
            "type": "CollectInvestigationPackage",
            "scope": null,
            "requestor": "Analyst@contoso.com",
            "requestorComment": "test",
            "status": "Succeeded",
            "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
            "computerDnsName": "desktop-39g9tgl",
            "creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z",
            "lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z",
            "relatedFileInfo": null
        },
        {
            "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
            "type": "RunAntiVirusScan",
            "scope": "Full",
            "requestor": "Analyst@contoso.com",
            "requestorComment": "Check machine for viruses due to alert 3212",
            "status": "Succeeded",
            "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
            "computerDnsName": "desktop-39g9tgl",
            "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
            "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
            "relatedFileInfo": null
        },
        {
            "id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
            "type": "StopAndQuarantineFile",
            "scope": null,
            "requestor": "Analyst@contoso.com",
            "requestorComment": "test",
            "status": "Succeeded",
            "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
            "computerDnsName": "desktop-39g9tgl",
            "creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z",
            "lastUpdateTimeUtc": "2018-12-04T12:16:14.2899973Z",
            "relatedFileInfo": {
                "fileIdentifier": "a0c659857ccbe457fdaf5fe21d54efdcbf6f6508",
                "fileIdentifierType": "Sha1"
            }
        }
    ]
}

Example 2

Example 2 request

Here's an example of a request that filters the MachineActions by machine ID and shows the latest two MachineActions.

GET https://api.security.microsoft.com/api/machineactions?$filter=machineId eq 'f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f'&$top=2

Example 2 response