The Cloud Monitoring API v3 lets you programmatically query and write metric data, organize monitored resources into groups, and manage dashboards, alerting policies, service-level objectives (SLOs), and notification channels. For method and resource specifications, see the [Cloud Monitoring API (REST)](https://docs.cloud.google.com/monitoring/api/ref_v3/rest) and [Cloud Monitoring API (gRPC)](https://docs.cloud.google.com/monitoring/api/ref_v3/rpc). ## Project names in the Monitoring API All of the methods in the Monitoring API have a required `name` parameter. This parameter typically has a description like the following: *Required. The project on which to execute the request. The format is: `projects/[PROJECT_ID_OR_NUMBER]`* In the Monitoring API, the value of `PROJECT_ID_OR_NUMBER` identifies one of the following:
- A Google Cloud project - A Google Cloud project that is also a [scoping project of a metrics scope](https://docs.cloud.google.com/monitoring/settings) Some methods in the Monitoring API require the project to be a scoping project of a metrics scope; other methods do not. A small number of methods can return different results, depending on the type of project. To describe these classes of methods, this discussion uses the term *metrics API* to refer to the following resources in the Monitoring API: - [`TimeSeries`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/TimeSeries) - [`MetricDescriptor`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors#MetricDescriptor) - [`MonitoredResourceDescriptor`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.monitoredResourceDescriptors#MonitoredResourceDescriptor) ### Scoping project of a metrics scope required All Monitoring API methods that are *not* part of the metrics API require the `name` parameter to refer to a scoping project of a metrics scope. ### Scoping project of a metrics scope not required None of the methods in the metrics API require the `name` parameter to refer to a scoping project of a metrics scope, but some methods behave differently when it does: - The following methods in the metrics API operate on the named Google Cloud project. These methods affect data only in the named project, regardless of whether the project is also a scoping project of a metrics scope. - `timeSeries.create` - `metricDescriptors.create` - `metricDescriptors.delete` - `metricDescriptors.get` - `monitoredResourceDescriptors.get` - The remaining methods in the metrics API behave as follows: - If the named project is not a scoping project of a metrics scope, then the methods retrieve data only from the named project. - If the named project is also a scoping project of a metrics scope, then the methods retrieve data from both the named project and any projects it monitors. The methods in this group are the following: - `timeSeries.list` - `timeSeries.query` - `metricDescriptors.list` - `monitoredResourceDescriptors.list` For information on setting up a Google Cloud project as a scoping project of a metrics scope, see [Metrics scopes overview](https://docs.cloud.google.com/monitoring/settings). ## API resources ### Metrics The Monitoring API gives you access to approximately [6,500 Cloud Monitoring metrics](https://docs.cloud.google.com/monitoring/api/metrics) from Google Cloud and Amazon Web Services. You can create your own custom metrics and organize your cloud resources using groups. For an introduction to metric concepts and the data structures that represent them, see [Metrics, time series, and resources](https://docs.cloud.google.com/monitoring/api/v3/metrics). To learn how to manage your custom metrics and the built-in metrics, see [User-defined metrics overview](https://docs.cloud.google.com/monitoring/custom-metrics). For a complete list of available metrics, see [Metrics list](https://docs.cloud.google.com/monitoring/api/metrics). ### Monitored resources A **monitored resource** is something about which metrics are collected. For example, you might be interested in the activity of a VM instance or a piece of hardware. For a list of the available monitored resources, see the [Monitored resource list](https://docs.cloud.google.com/monitoring/api/resources). ### Monitored-resource groups A **group** is a dynamic collection of monitored resources. You have always been able to create groups manually in the Google Cloud console, and you can also use the Cloud Monitoring API to write code that creates and uses groups. For more information, see the API reference for [`Group`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.groups#Group). ### Alerting policies An **alerting policy** is a configuration resource that describes the criteria for generating alerts and how to notify you when those alerts are created. [Alerting overview](https://docs.cloud.google.com/monitoring/alerts) explains the basic concepts of alerting policies. For more information, see the API reference for [`AlertPolicy`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies#AlertPolicy). The API also lets you create alerting policies based on a ratio of two metrics. Ratios cannot currently be created by using Monitoring in the Google Cloud console. For more information, see [`MetricThreshold`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies#MetricThreshold) in the [`AlertPolicy` reference](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies#AlertPolicy). ### Notification channels > [!WARNING] > > **Beta** > > > This product or feature is > > subject to the "Pre-GA Offerings Terms" in the General Service Terms section > of the [Service Specific > Terms](https://docs.cloud.google.com/terms/service-terms#1). > > Pre-GA products and features are available "as is" and might have limited support. > > For more information, see the > [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages). A **notification channel** is a configuration resource that describes how to notify you when alerts occur. Notification channels can reference a variety of different kinds of communication services and endpoints; these are specified in *descriptors*. The descriptors determine the set of configuration parameters that are included in a channel object. For more information, see the [`NotificationChannel` reference](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.notificationChannels) and the [`NotificationChannelDescriptor` reference](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.notificationChannelDescriptors). ### Service monitoring The **service monitoring** resources are used to set up service-level objectives that can be used to monitor the health of your services. Service Monitoring adds the following resources to the Monitoring API: - [`services`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/services) - [`services.serviceLevelObjectives`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/services.serviceLevelObjectives) For more information about these service-monitoring concepts and about using the API, see [SLO monitoring](https://docs.cloud.google.com/stackdriver/docs/solutions/slo-monitoring). ### Dashboards You can programmatically create and manipulate both dashboards and charts using the [`Dashboards`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v1/projects.dashboards) endpoint. For information on using this endpoint to manage dashboards and charts, see [Create and manage dashboards by API](https://docs.cloud.google.com/monitoring/dashboards/api-dashboard). ### Monitoring Query Language > [!CAUTION] > **Announcement:** On July 22, 2025, Google Cloud customer support for MQL ended, and MQL is no longer available in the Google Cloud console when you create charts, dashboards, and alerting policies. Existing MQL charts, dashboards, and alerting policies continue to work, and you can still create them by using the Cloud Monitoring API. For more information, see the [deprecation notice for MQL](https://docs.cloud.google.com/stackdriver/docs/deprecations/mql). Monitoring Query Language (MQL) provides a text-based interface for querying Cloud Monitoring time-series data. MQL uses a piped-query model and is more expressive than Monitoring filters. You can use MQL queries from the Monitoring API or from the code editor. For general information on MQL, see [Monitoring Query Language overview](https://docs.cloud.google.com/monitoring/mql). For information on using MQL to retrieve time-series data by using the Monitoring API, see the API reference for the [`timeSeries.query`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries/query) method. ## Filters The Monitoring API uses filters to select metrics, to fetch time-series data, and to collect monitored resources into groups. For more information, see [Monitoring filters](https://docs.cloud.google.com/monitoring/api/v3/filters). The Monitoring API also uses filters to restrict the result set of certain `list` operations. See [Reference: Sorting and filtering](https://docs.cloud.google.com/monitoring/api/v3/sorting-and-filtering) for details on managing the results of the [`alertPolicies.list`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alertPolicies/list) and [`notificationChannels.list`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.notificationChannels/list) methods. ## Next steps - See the introduction to [Metrics, time series, and resources](https://docs.cloud.google.com/monitoring/api/v3/metrics). - See [Alerting overview](https://docs.cloud.google.com/monitoring/alerts). - See how to call API methods from the [APIs Explorer](https://docs.cloud.google.com/monitoring/api/apis-explorer). - See how to use the text-based [Monitoring Query Language](https://docs.cloud.google.com/monitoring/mql) for querying time-series data. - See the [client libraries for Cloud Monitoring](https://docs.cloud.google.com/monitoring/docs/reference/libraries) to get started with Cloud Monitoring in your language of choice. - See the API reference, [Cloud Monitoring API (REST)](https://docs.cloud.google.com/monitoring/api/ref_v3/rest) or [Cloud Monitoring API (gRPC)](https://docs.cloud.google.com/monitoring/api/ref_v3/rpc).