Resources - Resources

Service:: Azure Resource Graph

API Version:: 2024-04-01

Queries the resources managed by Azure Resource Manager for scopes specified in the request.

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

URI Parameters

Name	In	Required	Type	Description
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
query	True	string	The resources query.
facets		FacetRequest[]	An array of facet requests to be computed against the query result.
managementGroups		string[]	Azure management groups against which to execute the query. Example: [ 'mg1', 'mg2' ]
options		QueryRequestOptions	The query evaluation options
subscriptions		string[]	Azure subscriptions against which to execute the query.

Responses

Name	Type	Description
200 OK	QueryResponse	The request has succeeded.
Other Status Codes	ResourceGraphCommon.ErrorResponse	An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Access a properties field

Basic management group query

Basic query

Basic tenant query

Complex query

Filter resources

First page query

Next page query

Query with a facet request

Random page query

Summarize resources by location

Access a properties field

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "query": "Resources | where type =~ 'Microsoft.Compute/virtualMachines' | summarize count() by tostring(properties.storageProfile.osDisk.osType)",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "count": 2,
  "data": [
    {
      "count": 7,
      "properties_storageProfile_osDisk_osType": "Linux"
    },
    {
      "count": 23,
      "properties_storageProfile_osDisk_osType": "Windows"
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 2
}

Basic management group query

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "managementGroups": [
    "e927f598-c1d4-4f72-8541-95d83a6a4ac8",
    "ProductionMG"
  ],
  "query": "Resources | project id, name, type, location, tags | limit 3"
}

Sample response

Status code:: 200

{
  "count": 3,
  "data": [
    {
      "name": "myNetworkInterface",
      "type": "microsoft.network/networkinterfaces",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Network/networkInterfaces/myNetworkInterface",
      "location": "centralus",
      "tags": {
        "tag1": "Value1"
      }
    },
    {
      "name": "myVnet",
      "type": "microsoft.network/virtualnetworks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/virtualNetworks/myVnet",
      "location": "westus",
      "tags": {}
    },
    {
      "name": "myPublicIp",
      "type": "microsoft.network/publicipaddresses",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/publicIPAddresses/myPublicIp",
      "location": "westus",
      "tags": {}
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 3
}

Basic query

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "query": "Resources | project id, name, type, location, tags | limit 3",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "count": 3,
  "data": [
    {
      "name": "myNetworkInterface",
      "type": "microsoft.network/networkinterfaces",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Network/networkInterfaces/myNetworkInterface",
      "location": "centralus",
      "tags": {
        "tag1": "Value1"
      }
    },
    {
      "name": "myVnet",
      "type": "microsoft.network/virtualnetworks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/virtualNetworks/myVnet",
      "location": "westus",
      "tags": {}
    },
    {
      "name": "myPublicIp",
      "type": "microsoft.network/publicipaddresses",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/publicIPAddresses/myPublicIp",
      "location": "westus",
      "tags": {}
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 3
}

Basic tenant query

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "query": "Resources | project id, name, type, location, tags | limit 3"
}

Sample response

Status code:: 200

{
  "count": 3,
  "data": [
    {
      "name": "myNetworkInterface",
      "type": "microsoft.network/networkinterfaces",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Network/networkInterfaces/myNetworkInterface",
      "location": "centralus",
      "tags": {
        "tag1": "Value1"
      }
    },
    {
      "name": "myVnet",
      "type": "microsoft.network/virtualnetworks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/virtualNetworks/myVnet",
      "location": "westus",
      "tags": {}
    },
    {
      "name": "myPublicIp",
      "type": "microsoft.network/publicipaddresses",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Network/publicIPAddresses/myPublicIp",
      "location": "westus",
      "tags": {}
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 3
}

Complex query

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "query": "Resources | project id, name, type, location | where type =~ 'Microsoft.Compute/virtualMachines' | summarize count() by location | top 3 by count_",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "count": 3,
  "data": [
    {
      "count_": 11,
      "location": "centralus"
    },
    {
      "count_": 11,
      "location": "eastus"
    },
    {
      "count_": 3,
      "location": "southcentralus"
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 3
}

Filter resources

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "query": "Resources | project id, name, type, location | where type =~ 'Microsoft.Compute/virtualMachines' | limit 3",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "count": 3,
  "data": [
    {
      "name": "myVm1",
      "type": "microsoft.compute/virtualmachines",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/virtualMachines/myVm1",
      "location": "centralus"
    },
    {
      "name": "myVirtualMachine",
      "type": "microsoft.compute/virtualmachines",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Compute/virtualMachines/myVirtualMachine",
      "location": "eastus"
    },
    {
      "name": "testVm",
      "type": "microsoft.compute/virtualmachines",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG3/providers/Microsoft.Compute/virtualMachines/testVm",
      "location": "eastus"
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 3
}

First page query

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "options": {
    "$skip": 0,
    "$top": 3
  },
  "query": "Resources | where name contains 'test' | project id, name, type, location",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "$skipToken": "eyAibm8iOiAibHVjayIsICJidXQiOiAibmljZSIsICJ0cnkiOiAiISIgfQ==",
  "count": 3,
  "data": [
    {
      "name": "yetanothertest_OsDisk_1_f396cbcb625a457bb69fe2abf5975820",
      "type": "microsoft.compute/disks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/disks/yetanothertest_OsDisk_1_f396cbcb625a457bb69fe2abf5975820",
      "location": "eastus"
    },
    {
      "name": "TestAA",
      "type": "microsoft.automation/automationaccounts",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/TestAA",
      "location": "westcentralus"
    },
    {
      "name": "TestRB",
      "type": "microsoft.automation/automationaccounts/runbooks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/TestAA/runbooks/TestRB",
      "location": "westcentralus"
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 386
}

Next page query

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "options": {
    "$skipToken": "eyAibm8iOiAibHVjayIsICJidXQiOiAibmljZSIsICJ0cnkiOiAiISIgfQ=="
  },
  "query": "Resources | where name contains 'test' | project id, name, type, location",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "$skipToken": "eyAibm8yIjogImx1Y2syIiwgImJ1dDIiOiAibmljZTIiLCAidHJ5MiI6ICIhIiB9",
  "count": 3,
  "data": [
    {
      "name": "second_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "type": "microsoft.compute/disks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/disks/second_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "location": "eastus"
    },
    {
      "name": "AATest",
      "type": "microsoft.automation/automationaccounts",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/AATest",
      "location": "westcentralus"
    },
    {
      "name": "RBTest",
      "type": "microsoft.automation/automationaccounts/runbooks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/TestAA/runbooks/RBTest",
      "location": "westcentralus"
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 386
}

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "facets": [
    {
      "expression": "location",
      "options": {
        "$top": 3,
        "sortOrder": "desc"
      }
    },
    {
      "expression": "properties.storageProfile.osDisk.osType",
      "options": {
        "$top": 3,
        "sortOrder": "desc"
      }
    },
    {
      "expression": "nonExistingColumn",
      "options": {
        "$top": 3,
        "sortOrder": "desc"
      }
    },
    {
      "expression": "resourceGroup",
      "options": {
        "$top": 3,
        "sortBy": "tolower(resourceGroup)",
        "sortOrder": "asc"
      }
    },
    {
      "expression": "resourceGroup",
      "options": {
        "$top": 3,
        "filter": "resourceGroup contains 'test'"
      }
    }
  ],
  "query": "Resources | where type =~ 'Microsoft.Compute/virtualMachines' | project id, name, location, resourceGroup, properties.storageProfile.osDisk.osType | limit 5",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "count": 5,
  "data": [
    {
      "name": "myTestVm",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/B-TEST-RG/providers/Microsoft.Compute/virtualMachines/myTestVm",
      "location": "eastus",
      "properties_storageProfile_osDisk_osType": "Windows",
      "resourceGroup": "B-TEST-RG"
    },
    {
      "name": "myTestAccountVm",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/c-rg/providers/Microsoft.Compute/virtualMachines/myTestAccountVm",
      "location": "westcentralus",
      "properties_storageProfile_osDisk_osType": "Windows",
      "resourceGroup": "c-rg"
    },
    {
      "name": "yetanothertest",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/I-RG/providers/Microsoft.Compute/virtualMachines/yetanothertest",
      "location": "eastus",
      "properties_storageProfile_osDisk_osType": "Linux",
      "resourceGroup": "I-RG"
    },
    {
      "name": "drafttest1bux4cv7a7q3aw",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/x-test-rg/providers/Microsoft.Compute/virtualMachines/drafttest1bux4cv7a7q3aw",
      "location": "southcentralus",
      "properties_storageProfile_osDisk_osType": "Linux",
      "resourceGroup": "x-test-rg"
    },
    {
      "name": "testvmntp25370",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/y-rg/providers/Microsoft.Compute/virtualMachines/testvmntp25370",
      "location": "eastus",
      "properties_storageProfile_osDisk_osType": "Windows",
      "resourceGroup": "y-rg"
    }
  ],
  "facets": [
    {
      "count": 3,
      "data": [
        {
          "count": 3,
          "location": "eastus"
        },
        {
          "count": 1,
          "location": "southcentralus"
        },
        {
          "count": 1,
          "location": "westcentralus"
        }
      ],
      "expression": "location",
      "resultType": "FacetResult",
      "totalRecords": 3
    },
    {
      "count": 2,
      "data": [
        {
          "count": 2,
          "properties_storageProfile_osDisk_osType": "Linux"
        },
        {
          "count": 3,
          "properties_storageProfile_osDisk_osType": "Windows"
        }
      ],
      "expression": "properties.storageProfile.osDisk.osType",
      "resultType": "FacetResult",
      "totalRecords": 2
    },
    {
      "errors": [
        {
          "code": "NoValidColumns",
          "message": "No valid columns in facet expression."
        },
        {
          "code": "InvalidColumnNames",
          "message": "Invalid column names: [nonExistingColumn]."
        }
      ],
      "expression": "nonExistingColumn",
      "resultType": "FacetError"
    },
    {
      "count": 3,
      "data": [
        {
          "count": 1,
          "resourceGroup": "B-TEST-RG"
        },
        {
          "count": 1,
          "resourceGroup": "c-rg"
        },
        {
          "count": 1,
          "resourceGroup": "I-RG"
        }
      ],
      "expression": "resourceGroup",
      "resultType": "FacetResult",
      "totalRecords": 5
    },
    {
      "count": 2,
      "data": [
        {
          "count": 1,
          "resourceGroup": "B-TEST-RG"
        },
        {
          "count": 1,
          "resourceGroup": "x-test-rg"
        }
      ],
      "expression": "resourceGroup",
      "resultType": "FacetResult",
      "totalRecords": 2
    }
  ],
  "resultTruncated": "false",
  "totalRecords": 5
}

Random page query

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "options": {
    "$skip": 10,
    "$top": 2
  },
  "query": "Resources | where name contains 'test' | project id, name, type, location",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "$skipToken": "eyAibm8iOiAibHVjayIsICJidXQiOiAibmljZSIsICJ0cnkiOiAiISIgfQ==",
  "count": 2,
  "data": [
    {
      "name": "third_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "type": "microsoft.compute/disks",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG1/providers/Microsoft.Compute/disks/third_OsDisk_dddddbcb625a457bb69fe2abf5975820",
      "location": "eastus"
    },
    {
      "name": "CCTest",
      "type": "microsoft.automation/automationaccounts",
      "id": "/subscriptions/cfbbd179-59d2-4052-aa06-9270a38aa9d6/resourceGroups/RG2/providers/Microsoft.Automation/automationAccounts/CCTest",
      "location": "westcentralus"
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 386
}

Summarize resources by location

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2024-04-01

{
  "query": "Resources | project id, name, type, location | summarize by location",
  "subscriptions": [
    "cfbbd179-59d2-4052-aa06-9270a38aa9d6"
  ]
}

Sample response

Status code:: 200

{
  "count": 3,
  "data": [
    {
      "location": "centralus"
    },
    {
      "location": "eastus"
    },
    {
      "location": "westus"
    }
  ],
  "facets": [],
  "resultTruncated": "false",
  "totalRecords": 3
}

Definitions

Name	Description
AuthorizationScopeFilter	Defines what level of authorization resources should be returned based on the which subscriptions and management groups are passed as scopes.
FacetError	A facet whose execution resulted in an error.
FacetRequest	A request to compute additional statistics (facets) over the query results.
FacetRequestOptions	The options for facet evaluation
FacetResult	Successfully executed facet containing additional statistics on the response of a query.
FacetSortOrder	The sorting order by the selected column (count by default).
QueryRequest	Describes a query to be executed.
QueryRequestOptions	The options for query evaluation
QueryResponse	Query result.
ResourceGraphCommon.Error	Error info.
ResourceGraphCommon.ErrorDetails	Error details.
ResourceGraphCommon.ErrorResponse	Error response.
ResultFormat	Defines in which format query result returned.
ResultTruncated	Indicates whether the query results are truncated.

AuthorizationScopeFilter

Enumeration

Defines what level of authorization resources should be returned based on the which subscriptions and management groups are passed as scopes.

Value	Description
AtScopeAndBelow	AtScopeAndBelow
AtScopeAndAbove	AtScopeAndAbove
AtScopeExact	AtScopeExact
AtScopeAboveAndBelow	AtScopeAboveAndBelow

FacetError

Object

A facet whose execution resulted in an error.

Name	Type	Description
errors	ResourceGraphCommon.ErrorDetails[]	An array containing detected facet errors with details.
expression	string	Facet expression, same as in the corresponding facet request.
resultType	string: FacetError	Result type

FacetRequest

Object

A request to compute additional statistics (facets) over the query results.

Name	Type	Description
expression	string	The column or list of columns to summarize by
options	FacetRequestOptions	The options for facet evaluation

FacetRequestOptions

Object

The options for facet evaluation

Name	Type	Default value	Description
$top	integer (int32) minimum: 1 maximum: 1000		The maximum number of facet rows that should be returned.
filter	string		Specifies the filter condition for the 'where' clause which will be run on main query's result, just before the actual faceting.
sortBy	string		The column name or query expression to sort on. Defaults to count if not present.
sortOrder	FacetSortOrder	desc	The sorting order by the selected column (count by default).

FacetResult

Object

Successfully executed facet containing additional statistics on the response of a query.

Name	Type	Description
count	integer (int32)	Number of records returned in the facet response.
data		A JObject array or Table containing the desired facets. Only present if the facet is valid.
expression	string	Facet expression, same as in the corresponding facet request.
resultType	string: FacetResult	Result type
totalRecords	integer (int64)	Number of total records in the facet results.

FacetSortOrder

Enumeration

The sorting order by the selected column (count by default).

Value	Description
asc	asc
desc	desc

QueryRequest

Object

Describes a query to be executed.

Name	Type	Description
facets	FacetRequest[]	An array of facet requests to be computed against the query result.
managementGroups	string[]	Azure management groups against which to execute the query. Example: [ 'mg1', 'mg2' ]
options	QueryRequestOptions	The query evaluation options
query	string	The resources query.
subscriptions	string[]	Azure subscriptions against which to execute the query.

QueryRequestOptions

Object

The options for query evaluation

Name	Type	Default value	Description
$skip	integer (int32) minimum: 0		The number of rows to skip from the beginning of the results. Overrides the next page offset when `$skipToken` property is present.
$skipToken	string		Continuation token for pagination, capturing the next page size and offset, as well as the context of the query.
$top	integer (int32) minimum: 1 maximum: 1000		The maximum number of rows that the query should return. Overrides the page size when `$skipToken` property is present.
allowPartialScopes	boolean	False	Only applicable for tenant and management group level queries to decide whether to allow partial scopes for result in case the number of subscriptions exceed allowed limits.
authorizationScopeFilter	AuthorizationScopeFilter	AtScopeAndBelow	Defines what level of authorization resources should be returned based on the which subscriptions and management groups are passed as scopes.
resultFormat	ResultFormat	objectArray	Defines in which format query result returned.

QueryResponse

Object

Query result.

Name	Type	Description
$skipToken	string	When present, the value can be passed to a subsequent query call (together with the same query and scopes used in the current request) to retrieve the next page of data.
count	integer (int64)	Number of records returned in the current response. In the case of paging, this is the number of records in the current page.
data		Query output in JObject array or Table format.
facets	Facet[]: FacetError[] FacetResult[]	Query facets.
resultTruncated	ResultTruncated	Indicates whether the query results are truncated.
totalRecords	integer (int64)	Number of total records matching the query.

ResourceGraphCommon.Error

Object

Error info.

Name	Type	Description
code	string	Error code identifying the specific error.
details	ResourceGraphCommon.ErrorDetails[]	Error details
message	string	A human readable error message.

ResourceGraphCommon.ErrorDetails

Object

Error details.

Name	Type	Description
code	string	Error code identifying the specific error.
message	string	A human readable error message.

ResourceGraphCommon.ErrorResponse

Object

Error response.

Name	Type	Description
error	ResourceGraphCommon.Error	Error info. Error information.

ResultFormat

Enumeration

Defines in which format query result returned.

Value	Description
table	table
objectArray	objectArray

ResultTruncated

Enumeration

Indicates whether the query results are truncated.

Value	Description
true	true
false	false