Azure monitoring REST API walkthrough - Azure Monitor (2024)

  • Article

This article shows you how to use the Azure Monitor REST API reference.

Retrieve metric definitions, dimension values, and metric values using the Azure Monitor API and use the data in your applications, or store in a database for analysis. You can also list alert rules and view activity logs using the Azure Monitor API.

Authenticate Azure Monitor requests

Request submitted using the Azure Monitor API use the Azure Resource Manager authentication model. All requests are authenticated with Microsoft Entra ID. One approach to authenticating the client application is to create a Microsoft Entra service principal and retrieve an authentication token. You can create a Microsoft Entra service principal using the Azure portal, CLI, or PowerShell. For more information, see Register an App to request authorization tokens and work with APIs.

Retrieve a token

Once you've created a service principal, retrieve an access token. Specify resource=https://management.azure.com in the token request.

Get an authentication token using any of the following methods:

  • CLI
  • REST API
  • SDK

When requesting a token, you must provide a resource parameter. The resource parameter is the URL of the resource you want to access.

Resources include:

  • https://management.azure.com
  • https://api.loganalytics.io
  • https://monitoring.azure.com
  • REST
  • CLI
  • SDK

Get a token using a REST request

Use the following REST API call to get a token.This request uses a client ID and client secret to authenticate the request. The client ID and client secret are obtained when you register your application with Microsoft Entra ID. For more information, see Register an App to request authorization tokens and work with APIs

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \-H 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant_type=client_credentials' \--data-urlencode 'client_id=<your apps client ID>' \--data-urlencode 'client_secret=<your apps client secret' \--data-urlencode 'resource=https://monitoring.azure.com'

The response body appears in the following format:

{ "token_type": "Bearer", "expires_in": "86399", "ext_expires_in": "86399", "expires_on": "1672826207", "not_before": "1672739507", "resource": "https://monitoring.azure.com", "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"}

After authenticating and retrieving a token, use the access token in your Azure Monitor API requests by including the header 'Authorization: Bearer <access token>'

Retrieve the resource ID

Using the REST API requires the resource ID of the target Azure resource.Resource IDs follow the following pattern:

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/<provider>/<resource name>/

For example

  • Azure IoT Hub: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Devices/IotHubs/<iot-hub-name>
  • Elastic SQL pool: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Sql/servers/<pool-db>/elasticpools/<sql-pool-name>
  • Azure SQL Database (v12): /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Sql/servers/<server-name>/databases/<database-name>
  • Azure Service Bus: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ServiceBus/<namespace>/<servicebus-name>
  • Azure Virtual Machine Scale Sets: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Compute/virtualMachineScaleSets/<vm-name>
  • Azure Virtual Machines: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Compute/virtualMachines/<vm-name>
  • Azure Event Hubs: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.EventHub/namespaces/<eventhub-namespace>

Use the Azure portal, PowerShell, or the Azure CLI to find the resource ID.

  • Azure portal
  • PowerShell
  • Azure CLI

To find the resourceID in the portal, from the resource's overview page, select JSON view

The Resource JSON page is displayed. The resource ID can be copied using the icon on the right of the ID.

API endpoints

The API endpoints use the following pattern:
/<resource URI>/providers/microsoft.insights/<metrics|metricDefinitions>?api-version=<apiVersion>
The resource URI is composed of the following components:
/subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/

Important

Be sure to include /providers/microsoft.insights/ after the resource URI when you make an API call to retrieve metrics or metric definitions.

Retrieve metric definitions

Use the Azure Monitor Metric Definitions REST API to access the list of metrics that are available for a service.Use the following request format to retrieve metric definitions.

GET /subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/providers/microsoft.insights/metricDefinitions?api-version=<apiVersion>Host: management.azure.comContent-Type: application/jsonAuthorization: Bearer <access token>

For example, The following request retrieves the metric definitions for an Azure Storage account.

curl --location --request GET 'https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01'--header 'Authorization: Bearer eyJ0eXAiOi...xYz

The following JSON shows an example response body.In this example, only the second metric has dimensions.

{ "value": [ { "id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricdefinitions/UsedCapacity", "resourceId": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage", "namespace": "Microsoft.Storage/storageAccounts", "category": "Capacity", "name": { "value": "UsedCapacity", "localizedValue": "Used capacity" }, "isDimensionRequired": false, "unit": "Bytes", "primaryAggregationType": "Average", "supportedAggregationTypes": [ "Total", "Average", "Minimum", "Maximum" ], "metricAvailabilities": [ { "timeGrain": "PT1H", "retention": "P93D" }, ... { "timeGrain": "PT12H", "retention": "P93D" }, { "timeGrain": "P1D", "retention": "P93D" } ] }, { "id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricdefinitions/Transactions", "resourceId": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage", "namespace": "Microsoft.Storage/storageAccounts", "category": "Transaction", "name": { "value": "Transactions", "localizedValue": "Transactions" }, "isDimensionRequired": false, "unit": "Count", "primaryAggregationType": "Total", "supportedAggregationTypes": [ "Total" ], "metricAvailabilities": [ { "timeGrain": "PT1M", "retention": "P93D" }, { "timeGrain": "PT5M", "retention": "P93D" }, ... { "timeGrain": "PT30M", "retention": "P93D" }, { "timeGrain": "PT1H", "retention": "P93D" }, ... { "timeGrain": "P1D", "retention": "P93D" } ], "dimensions": [ { "value": "ResponseType", "localizedValue": "Response type" }, { "value": "GeoType", "localizedValue": "Geo type" }, { "value": "ApiName", "localizedValue": "API name" } ] }, ... ]}

Note

We recommend using API version "2018-01-01" or later. Older versions of the metric definitions API don't support dimensions.

Retrieve dimension values

After the retrieving the available metric definitions, retrieve the range of values for the metric's dimensions. Use dimension values to filter or segment the metrics in your queries. Use the Azure Monitor Metrics REST API to find all of the values for a given metric dimension.

Use the metric's name.value element in the filter definitions. If no filters are specified, the default metric is returned. The API only allows one dimension to have a wildcard filter.Specify the request for dimension values using the "resultType=metadata" query parameter. The resultType is omitted for a metric values request.

Note

To retrieve dimension values by using the Azure Monitor REST API, use the API version "2019-07-01" or later.

Use the following request format to retrieve dimension values.

GET /subscriptions/<subscription-id>/resourceGroups/ <resource-group-name>/providers/<resource-provider-namespace>/ <resource-type>/<resource-name>/providers/microsoft.insights/ metrics?metricnames=<metric> &timespan=<starttime/endtime> &$filter=<filter> &resultType=metadata &api-version=<apiVersion> HTTP/1.1Host: management.azure.comContent-Type: application/jsonAuthorization: Bearer <access token>

The following example retrieves the list of dimension values that were emitted for the API Name dimension of the Transactions metric, where the GeoType dimension has a value of Primary, for the specified time range.

curl --location --request GET 'https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics \?metricnames=Transactions \&timespan=2023-03-01T00:00:00Z/2023-03-02T00:00:00Z \&resultType=metadata \&$filter=GeoType eq \'Primary\' and ApiName eq \'*\' \&api-version=2019-07-01'-header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJ0e..meG1lWm9Y'

The following JSON shows an example response body.

{ "timespan": "2023-03-01T00:00:00Z/2023-03-02T00:00:00Z", "value": [ { "id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/Microsoft.Insights/metrics/Transactions", "type": "Microsoft.Insights/metrics", "name": { "value": "Transactions", "localizedValue": "Transactions" }, "unit": "Count", "timeseries": [ { "metadatavalues": [ { "name": { "value": "apiname", "localizedValue": "apiname" }, "value": "DeleteBlob" } ] }, { "metadatavalues": [ { "name": { "value": "apiname", "localizedValue": "apiname" }, "value": "SetBlobProperties" } ] }, ... ] } ], "namespace": "Microsoft.Storage/storageAccounts", "resourceregion": "eastus"}

Retrieve metric values

After retrieving the metric definitions and dimension values, retrieve the metric values. Use the Azure Monitor Metrics REST API to retrieve the metric values.

Use the metric's name.value element in the filter definitions. If no dimension filters are specified, the rolled up, aggregated metric is returned.

Multiple time series

A time series is a set of data points that are ordered by time for a given combination of dimensions. A dimension is an aspect of the metric that describes the data point such as resource Id, region, or ApiName.

  • To fetch multiple time series with specific dimension values, specify a filter query parameter that specifies both dimension values such as "&$filter=ApiName eq 'ListContainers' or ApiName eq 'GetBlobServiceProperties'". In this example, you get a time series where ApiName is ListContainers and a second time series where ApiName is GetBlobServiceProperties.
  • To return a time series for every value of a given dimension, use an * filter such as "&$filter=ApiName eq '*'". Use the Top and OrderBy query parameters to limit and sort the number of time series returned. In this example, you get a time series for every value of ApiNamein the result set. If no data is returned, the API returns an empty time series "timeseries": [].

Note

To retrieve multi-dimensional metric values using the Azure Monitor REST API, use the API version "2019-07-01" or later.

Use the following request format to retrieve metric values.

GET /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/<resource-provider-namespace>/<resource-type>/<resource-name>/providers/microsoft.insights/metrics?metricnames=<metric>&timespan=<starttime/endtime>&$filter=<filter>&interval=<timeGrain>&aggregation=<aggreation>&api-version=<apiVersion>Host: management.azure.comContent-Type: application/jsonAuthorization: Bearer <access token>

The following example retrieves the top three APIs, by the number of Transactions in descending value order, during a 5-minute range, where the GeoType dimension has a value of Primary.

curl --location --request GET 'https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics \?metricnames=Transactions \&timespan=2023-03-01T02:00:00Z/2023-03-01T02:05:00Z \& $filter=apiname eq '\''GetBlobProperties'\'&interval=PT1M \&aggregation=Total \&top=3 \&orderby=Total desc \&api-version=2019-07-01"' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer yJ0eXAiOi...g1dCI6Ii1LS'

The following JSON shows an example response body.

{ "cost": 0, "timespan": "2023-03-01T02:00:00Z/2023-03-01T02:05:00Z", "interval": "PT1M", "value": [ { "id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/Microsoft.Insights/metrics/Transactions", "type": "Microsoft.Insights/metrics", "name": { "value": "Transactions", "localizedValue": "Transactions" }, "unit": "Count", "timeseries": [ { "metadatavalues": [ { "name": { "value": "apiname", "localizedValue": "apiname" }, "value": "GetBlobProperties" } ], "data": [ { "timeStamp": "2023-09-19T02:00:00Z", "total": 2 }, { "timeStamp": "2023-09-19T02:01:00Z", "total": 1 }, { "timeStamp": "2023-09-19T02:02:00Z", "total": 3 }, { "timeStamp": "2023-09-19T02:03:00Z", "total": 7 }, { "timeStamp": "2023-09-19T02:04:00Z", "total": 2 } ] }, ... ] } ], "namespace": "Microsoft.Storage/storageAccounts", "resourceregion": "eastus"}

Querying metrics for multiple resources at a time.

In addition to querying for metrics on an individual resource, some resource types also support querying for multiple resources in a single request. These APIs are what power the Multi-Resource experience in Azure metrics explorer. The set of resources types that support querying for multiple metrics can be seen on the Metrics blade in Azure monitor via the resource type drop-down in the scope selector on the context blade. For more information, see the Multi-Resource UX documentation.

There are some important differences between querying metrics for multiple and individual resources.

  • Metrics multi-resource APIs operate at the subscription level instead of the resource ID level. This restriction means users querying these APIs must have Monitoring Reader permissions on the subscription itself.
  • Metrics multi-resource APIs only support a single resourceType per query, which must be specified in the form of a metric namespace query parameter.
  • Metrics multi-resource APIs only support a single Azure region per query, which must be specified in the form of a region query parameter.

Querying metrics for multiple resources examples

The following example shows an individual metric definitions request:

GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM1/providers/microsoft.insights/metricdefinitions?api-version=2021-05-01

The following request shows the equivalent metric definitions request for multiple resources.The only changes are the subscription path instead of a resource ID path, and the addition of region and metricNamespace query parameters.

GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/metricdefinitions?api-version=2021-05-01&region=eastus&metricNamespace=microsoft.compute/virtualmachines

The following example shows an individual metrics request.

GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM1/providers/microsoft.Insights/metrics?timespan=2023-06-25T22:20:00.000Z/2023-06-26T22:25:00.000Z&interval=PT5M&metricnames=Percentage CPU&aggregation=average&api-version=2021-05-01

Below is an equivalent metrics request for multiple resources:

GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.Insights/metrics?timespan=2023-06-25T22:20:00.000Z/2023-06-26T22:25:00.000Z&interval=PT5M&metricnames=Percentage CPU&aggregation=average&api-version=2021-05-01&region=eastus&metricNamespace=microsoft.compute/virtualmachines&$filter=Microsoft.ResourceId eq '*'

Note

A Microsoft.ResourceId eq '*' filter is added in the example for the multi resource metrics requests. The * filter tells the API to return a separate time series for each virtual machine resource that has data in the subscription and region. Without the filter the API would return a single time series aggregating the average CPU for all VMs. The times series for each resource is differentiated by the Microsoft.ResourceId metadata value on each time series entry, as can be seen in the following sample return value. If there are no resourceIds retrieved by this query an empty time series"timeseries": [] is returned.

{ "timespan": "2023-06-25T22:35:00Z/2023-06-26T22:40:00Z", "interval": "PT6H", "value": [ { "id": "subscriptions/12345678-abcd-98765432-abcdef012345/providers/Microsoft.Insights/metrics/Percentage CPU", "type": "Microsoft.Insights/metrics", "name": { "value": "Percentage CPU", "localizedValue": "Percentage CPU" }, "displayDescription": "The percentage of allocated compute units that are currently in use by the Virtual Machine(s)", "unit": "Percent", "timeseries": [ { "metadatavalues": [ { "name": { "value": "Microsoft.ResourceId", "localizedValue": "Microsoft.ResourceId" }, "value": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM1" } ], "data": [ { "timeStamp": "2023-06-25T22:35:00Z", "average": 3.2618888888888886 }, { "timeStamp": "2023-06-26T04:35:00Z", "average": 4.696944444444445 }, { "timeStamp": "2023-06-26T10:35:00Z", "average": 6.19701388888889 }, { "timeStamp": "2023-06-26T16:35:00Z", "average": 2.630347222222222 }, { "timeStamp": "2023-06-26T22:35:00Z", "average": 21.288999999999998 } ] }, { "metadatavalues": [ { "name": { "value": "Microsoft.ResourceId", "localizedValue": "Microsoft.ResourceId" }, "value": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM2" } ], "data": [ { "timeStamp": "2023-06-25T22:35:00Z", "average": 7.567069444444444 }, { "timeStamp": "2023-06-26T04:35:00Z", "average": 5.111835883171071 }, { "timeStamp": "2023-06-26T10:35:00Z", "average": 10.078277777777778 }, { "timeStamp": "2023-06-26T16:35:00Z", "average": 8.399097222222222 }, { "timeStamp": "2023-06-26T22:35:00Z", "average": 2.647 } ] }, { "metadatavalues": [ { "name": { "value": "Microsoft.ResourceId", "localizedValue": "Microsoft.ResourceId" }, "value": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/Common-TESTING/providers/Microsoft.Compute/virtualMachines/CommonVM1" } ], "data": [ { "timeStamp": "2023-06-25T22:35:00Z", "average": 6.892319444444444 }, { "timeStamp": "2023-06-26T04:35:00Z", "average": 3.5054305555555554 }, { "timeStamp": "2023-06-26T10:35:00Z", "average": 8.398817802503476 }, { "timeStamp": "2023-06-26T16:35:00Z", "average": 6.841666666666667 }, { "timeStamp": "2023-06-26T22:35:00Z", "average": 3.3850000000000002 } ] } ], "errorCode": "Success" } ], "namespace": "microsoft.compute/virtualmachines", "resourceregion": "eastus"}

Troubleshooting querying metrics for multiple resources

  • Empty time series returned "timeseries": []

    • An empty time series is returned when no data is available for the specified time range and filter. The most common cause is specifying a time range that doesn't contain any data. For example, if the time range is set to a future date.
    • Another common cause is specifying a filter that doesn't match any resources. For example, if the filter specifies a dimension value that doesn't exist on any resources in the subscription and region combination, "timeseries": [] is returned.
  • Wildcard filters
    Using a wildcard filter such as Microsoft.ResourceId eq '*' causes the API to return a time series for every resourceId in the subscription and region. If the subscription and region combination contains no resources, an empty time series is returned. The same query without the wildcard filter would return a single time series, aggregating the requested metric over the requested dimensions, for example subscription and region.

  • 401 authorization errors:
    The individual resource metrics APIs requires a user have the Monitoring Reader permission on the resource being queried. Because the multi resource metrics APIs are subscription level APIs, users must have the Monitoring Reader permission for the queried subscription to use the multi resource metrics APIs. Even if users have Monitoring Reader on all the resources in a subscription, the request fails if the user doesn't have Monitoring Reader on the subscription itself.

Next steps

  • Review the overview of monitoring.
  • View the supported metrics with Azure Monitor.
  • Review the Microsoft Azure Monitor REST API reference.
  • Review the new Azure Monitor Query client libraries
  • Review the Azure Management Library.
  • Retrieve activity log data using Azure monitor REST API.
Azure monitoring REST API walkthrough - Azure Monitor (2024)
Top Articles
What is System Integration? Definition, Methods, Challenges | TechTarget
Why so many programmers are single?
AMC Theatre - Rent A Private Theatre (Up to 20 Guests) From $99+ (Select Theaters)
Odawa Hypixel
Dricxzyoki
Ffxiv Palm Chippings
Gamevault Agent
Optimal Perks Rs3
Mail Healthcare Uiowa
Braums Pay Per Hour
What Happened To Father Anthony Mary Ewtn
Cvs Devoted Catalog
Youtube Combe
Robot or human?
Johnston v. State, 2023 MT 20
Troy Athens Cheer Weebly
Discover Westchester's Top Towns — And What Makes Them So Unique
Darksteel Plate Deepwoken
Guidewheel lands $9M Series A-1 for SaaS that boosts manufacturing and trims carbon emissions | TechCrunch
Lima Funeral Home Bristol Ri Obituaries
Eka Vore Portal
Craigslist Farm And Garden Tallahassee Florida
Grasons Estate Sales Tucson
Telegram Scat
Does Breckie Hill Have An Only Fans – Repeat Replay
Divina Rapsing
Ukc Message Board
Routing Number For Radiant Credit Union
Boston Dynamics’ new humanoid moves like no robot you’ve ever seen
Mikayla Campinos: Unveiling The Truth Behind The Leaked Content
Yayo - RimWorld Wiki
Criglist Miami
Past Weather by Zip Code - Data Table
Ryujinx Firmware 15
Everything You Need to Know About Ñ in Spanish | FluentU Spanish Blog
Lincoln Financial Field, section 110, row 4, home of Philadelphia Eagles, Temple Owls, page 1
Raising Canes Franchise Cost
Wal-Mart 2516 Directory
Jason Brewer Leaving Fox 25
Gateway Bible Passage Lookup
Simnet Jwu
Postgraduate | Student Recruitment
Nail Salon Open On Monday Near Me
Joey Gentile Lpsg
Grand Valley State University Library Hours
'The Nun II' Ending Explained: Does the Immortal Valak Die This Time?
The Complete Uber Eats Delivery Driver Guide:
Best Restaurant In Glendale Az
Craigslist Psl
How Did Natalie Earnheart Lose Weight
Gelato 47 Allbud
Escape From Tarkov Supply Plans Therapist Quest Guide
Latest Posts
Article information

Author: Velia Krajcik

Last Updated:

Views: 5794

Rating: 4.3 / 5 (74 voted)

Reviews: 89% of readers found this page helpful

Author information

Name: Velia Krajcik

Birthday: 1996-07-27

Address: 520 Balistreri Mount, South Armand, OR 60528

Phone: +466880739437

Job: Future Retail Associate

Hobby: Polo, Scouting, Worldbuilding, Cosplaying, Photography, Rowing, Nordic skating

Introduction: My name is Velia Krajcik, I am a handsome, clean, lucky, gleaming, magnificent, proud, glorious person who loves writing and wants to share my knowledge and understanding with you.