List devices

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

Namespace: microsoft.graph

Retrieve a list of device objects registered in the organization.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	Device.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account)	Not supported.
Application	Device.Read.All, Device.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP request

GET /devices

Optional query parameters

This method supports the $count, $expand, $filter, $orderBy, $search, $select, and $top OData query parameters to help customize the response. Some queries are supported only when you use the ConsistencyLevel header set to eventual and $count. For more information, see Advanced query capabilities on Azure AD directory objects.

Request headers

Name	Description
Authorization	Bearer {token}. Required.
ConsistencyLevel	eventual. This header and $count are required when using $search, or in specific usage of $filter. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on Azure AD directory objects.

Request body

Do not supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and collection of device objects in the response body.

Examples

Example 1: Get a list of devices

Request

The following is an example of the request.

HTTP

GET https://graph.microsoft.com/v1.0/devices

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var devices = await graphClient.Devices
	.Request()
	.GetAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let devices = await client.api('/devices')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/devices"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
	completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

		NSError *jsonError = nil;
		MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
		MSGraphDevice *device = [[MSGraphDevice alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

DeviceCollectionPage devices = graphClient.devices()
	.buildRequest()
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

result, err := graphClient.Devices().Get()

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgDevice

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "accountEnabled":true,
      "deviceId":"00000000-0000-0000-0000-000000000000",
      "deviceVersion":1,
      "displayName":"contoso_Android",
      "Manufacturer":"Google",
      "Model":"Pixel 3a",
      "operatingSystemVersion":"10.0"
    }
  ]
}

Example 2: Get only a count of devices

Request

The following is an example of the request. This request requires the ConsistencyLevel header set to eventual because $count is in the request. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on Azure AD directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

GET https://graph.microsoft.com/v1.0/devices/$count
ConsistencyLevel: eventual

Response

The following is an example of the response.

HTTP/1.1 200 OK
Content-type: text/plain

294

Example 3: List all devices and return only their id and extensionAttributes properties

Request

GET https://graph.microsoft.com/beta/devices?$select=id,extensionAttributes

Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#devices(id,extensionAttributes)",
    "value": [
        {
            "id": "6a59ea83-02bd-468f-a40b-f2c3d1821983",
            "extensionAttributes": {
                "extensionAttribute1": null,
                "extensionAttribute2": null,
                "extensionAttribute3": null,
                "extensionAttribute4": null,
                "extensionAttribute5": null,
                "extensionAttribute6": null,
                "extensionAttribute7": null,
                "extensionAttribute8": null,
                "extensionAttribute9": null,
                "extensionAttribute10": null,
                "extensionAttribute11": null,
                "extensionAttribute12": null,
                "extensionAttribute13": null,
                "extensionAttribute14": null,
                "extensionAttribute15": null
            }
        }
    ]
}

Example 4: Use $filter and $top to get one device with a display name that starts with 'a' including a count of returned objects

Request

The following is an example of the request. This request requires the ConsistencyLevel header set to eventual and the $count=true query string because the request has both the $orderBy and $filter query parameters. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on Azure AD directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

GET https://graph.microsoft.com/v1.0/devices?$filter=startswith(displayName, 'a')&$count=true&$top=1&$orderby=displayName 
ConsistencyLevel: eventual

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#devices",
  "@odata.count":1,
  "value":[
    {
      "accountEnabled":true,
      "deviceId":"00000000-0000-0000-0000-000000000000",
      "deviceVersion":1,
      "displayName":"a_device_1",
      "Manufacturer":"Google",
      "Model":"Pixel 3a",
      "operatingSystemVersion":"10.0"
    }
  ]
}

Example 5: Use $search to get devices with display names that contain the letters 'Android' including a count of returned objects

Request

The following is an example of the request. This request requires the ConsistencyLevel header set to eventual because $search and the $count=true query string is in the request. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on Azure AD directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

HTTP

GET https://graph.microsoft.com/v1.0/devices?$search="displayName:Android"&$count=true
ConsistencyLevel: eventual

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var queryOptions = new List<QueryOption>()
{
	new QueryOption("$count", "true")
};

var devices = await graphClient.Devices
	.Request( queryOptions )
	.Header("ConsistencyLevel","eventual")
	.Search("displayName:Android")
	.GetAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let devices = await client.api('/devices')
	.header('ConsistencyLevel','eventual')
	.search('displayName:Android')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/devices?$search=%22displayName:Android%22&$count=true"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"eventual" forHTTPHeaderField:@"ConsistencyLevel"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
	completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

		NSError *jsonError = nil;
		MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
		MSGraphDevice *device = [[MSGraphDevice alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
requestOptions.add(new QueryOption("$search", "displayName:Android"));

DeviceCollectionPage devices = graphClient.devices()
	.buildRequest( requestOptions )
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DevicesRequestBuilderGetQueryParameters{
	Search: "%22displayName:Android%22",
	Count: true,
}
headers := map[string]string{
	"ConsistencyLevel": "eventual"
}
options := &msgraphsdk.DevicesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
	Headers: headers,
}
result, err := graphClient.Devices().GetWithRequestConfigurationAndResponseHandler(options, nil)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgDevice -Search "displayName:Android" -CountVariable CountVar -ConsistencyLevel eventual 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#devices",
  "@odata.count":1396,
  "value":[
    {
      "accountEnabled":true,
      "deviceId":"00000000-0000-0000-0000-000000000000",
      "deviceVersion":1,
      "displayName":"contoso_Android",
      "Manufacturer":"Google",
      "Model":"Pixel 3a",
      "operatingSystemVersion":"10.0"
    }
  ]
}

Example 6: Get device using filter on extensionAttributes

Request

The following is an example of the request. This request requires the ConsistencyLevel header set to eventual and the $count=true query string because the extensionAttributes property supports $filter only with advanced query parameters. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on Azure AD directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

HTTP

GET https://graph.microsoft.com/v1.0/devices?$filter=extensionAttributes/extensionAttribute1 eq 'BYOD-Device'&$count=true
ConsistencyLevel: eventual

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var queryOptions = new List<QueryOption>()
{
	new QueryOption("$count", "true")
};

var devices = await graphClient.Devices
	.Request( queryOptions )
	.Header("ConsistencyLevel","eventual")
	.Filter("extensionAttributes/extensionAttribute1 eq 'BYOD-Device'")
	.GetAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let devices = await client.api('/devices')
	.header('ConsistencyLevel','eventual')
	.filter('extensionAttributes/extensionAttribute1 eq \'BYOD-Device\'')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/devices?$filter=extensionAttributes/extensionAttribute1%20eq%20'BYOD-Device'&$count=true"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"eventual" forHTTPHeaderField:@"ConsistencyLevel"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
	completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

		NSError *jsonError = nil;
		MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
		MSGraphDevice *device = [[MSGraphDevice alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));

DeviceCollectionPage devices = graphClient.devices()
	.buildRequest( requestOptions )
	.filter("extensionAttributes/extensionAttribute1 eq 'BYOD-Device'")
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DevicesRequestBuilderGetQueryParameters{
	Filter: "extensionAttributes/extensionAttribute1%20eq%20'BYOD-Device'",
	Count: true,
}
headers := map[string]string{
	"ConsistencyLevel": "eventual"
}
options := &msgraphsdk.DevicesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
	Headers: headers,
}
result, err := graphClient.Devices().GetWithRequestConfigurationAndResponseHandler(options, nil)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgDevice -Filter "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'" -CountVariable CountVar -ConsistencyLevel eventual 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#devices",
    "@odata.count": 1,
    "value": [
        {
            "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/6a59ea83-02bd-468f-a40b-f2c3d1821983/Microsoft.DirectoryServices.Device",
            "id": "6a59ea83-02bd-468f-a40b-f2c3d1821983",
            "accountEnabled": true,
            "approximateLastSignInDateTime": "2021-10-21T06:36:56Z",
            "createdDateTime": "2021-09-21T15:16:30Z",
            "deviceId": "eab73519-780d-4d43-be6d-a4a89af2a348",
            "displayName": "DESKTOP-LK3PESR",
            "operatingSystem": "Windows",
            "operatingSystemVersion": "10.0.19043.1237",
            "physicalIds": [],
            "extensionAttributes": {
                "extensionAttribute1": "BYOD-Device",
                "extensionAttribute2": null,
                "extensionAttribute3": null,
                "extensionAttribute4": null,
                "extensionAttribute5": null,
                "extensionAttribute6": null,
                "extensionAttribute7": null,
                "extensionAttribute8": null,
                "extensionAttribute9": null,
                "extensionAttribute10": null,
                "extensionAttribute11": null,
                "extensionAttribute12": null,
                "extensionAttribute13": null,
                "extensionAttribute14": null,
                "extensionAttribute15": null
            },
            "alternativeSecurityIds": [
                {
                    "type": 2,
                    "identityProvider": null,
                    "key": "WAA1ADAAOQA6AD...QBnAD0A"
                }
            ]
        }
    ]
}