openapi: 3.0.0 info: contact: name: Confluent url: https://confluent.io email: support@confluent.io description: | # Introduction The Confluent Cloud Metrics API provides actionable operational metrics about your Confluent Cloud deployment. This is a queryable HTTP API in which the user will `POST` a query written in JSON and get back a time series of metrics specified by the query. Comprehensive documentation is available on [docs.confluent.io](https://docs.confluent.io/current/cloud/metrics-api.html). # Available Metrics Reference

Please see the Metrics Reference for a list of available metrics.

This information is also available programmatically via the [descriptors endpoint](#tag/Version-2/paths/~1v2~1metrics~1{dataset}~1descriptors~1metrics/get). # Authentication Confluent uses API keys for integrating with Confluent Cloud. Applications must be authorized and authenticated before they can access or manage resources in Confluent Cloud. You can manage your API keys in the Confluent Cloud Dashboard or Confluent Cloud CLI. An API key is owned by a User or Service Account and inherits the permissions granted to the owner. Today, you can divide API keys into two classes: * **Cloud API Keys** - These grant access to the Confluent Cloud Control Plane APIs, such as for Provisioning and Metrics integrations. * **Cluster API Keys** - These grant access to a single Confluent cluster, such as a specific Kafka or Schema Registry cluster. **If you are going to use an API Key, you must use a Cloud API Key**. Cluster API Keys won't work. Cloud API Keys can be created using the [Confluent Cloud CLI](https://docs.confluent.io/current/cloud/cli/). ``` ccloud api-key create --resource cloud ``` All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. The Confluent Cloud Metrics API also supports OAuth 2.0 by allowing Confluent Security Token Service (STS) tokens as credentials to authenticate to metrics API. See steps to [Authenticate access to Confluent Cloud APIs using Confluent STS tokens](https://docs.confluent.io/cloud/current/access-management/authenticate/oauth/access-rest-apis-sts.html#authenticate-access-to-ccloud-apis-using-confluent-security-token-service-sts-tokens) # Versioning Confluent APIs ensure stability for your integrations by avoiding the introduction of breaking changes to customers unexpectedly. Confluent will make non-breaking API changes without advance notice. Thus, API clients **must** follow the [Compatibility Policy](#section/Versioning/Compatibility-Policy) below to ensure your ingtegration remains stable. All APIs follow the API Lifecycle Policy described below, which describes the guarantees API clients can rely on. Breaking changes will be [widely communicated](#communication) in advance in accordance with our [Deprecation Policy](#section/Versioning/Deprecation-Policy). Confluent will provide timelines and a migration path for all API changes, where available. Be sure to subscribe to one or more [communication channels](#communication) so you don't miss any updates! One exception to these guidelines is for critical security issues. We will take any necessary actions to mitigate any critical security issue as soon as possible, which may include disabling the vulnerable functionality until a proper solution is available. Do not consume any Confluent API unless it is documented in the API Reference. All undocumented endpoints should be considered private, subject to change without notice, and not covered by any agreements. > Note: The "v1" in the URL is not a "major version" in the [Semantic Versioning](https://semver.org/) sense. It is a "generational version" or "meta version", as seen in other APIs like Github API or the Stripe API. ## Changelog ### 2026-06-18 #### Improved metric data freshness from 5 minutes to 3 minutes We have improved the freshness of our metric data from 5 minutes to 3 minutes. Metric data points are now available to the organisation within 3 minutes through the export endpoint. This is a fully backwards-compatible update that requires no action or changes from your end, so users utilizing the export endpoint for integrations like Grafana and Prometheus will see this performance improvement automatically. ### 2026-05-21 #### `/export` per-metric return limit raised to 60,000 data points The Metrics API /export endpoint now returns up to 60,000 data points per resource type per metric, increased from the previous limit of 30,000. Responses that previously truncated at 30,000 unique label combinations per metric will now include up to 60,000 before truncation. No client-side change is required. ### 2026-04-16 #### Partial success responses for `/export` endpoint The Metrics API now returns partial success responses when requests include inaccessible resources, such as deleted or unauthorized resources, instead of failing the entire request with a 403 Forbidden HTTP status code. A `confluent_scrape_resource_access_error` gauge metric is included in the response for each queried resource, with a value of `1` for inaccessible resources and `0` for accessible ones. If all requested resources are inaccessible, the request fails with a 403 Forbidden HTTP status code. ### 2025-10-09 #### Begin six month notice of forthcoming API behavior change. On April 9, 2026, the Metrics API will start returning partial success responses when requests include inaccessible resources, such as, deleted or unauthorized resources, instead of failing the entire request with 403 Forbidden HTTP status code. For more information, see Upcoming Improvement to the Confluent Cloud Metrics API /export Endpoint. ### 2022-12-01 #### The dataset `health-plus` is now available in preview. See the [Datasets](#section/Object-Model/Datasets) section for more details. ### 2022-10-18 #### `cluster_active_link_count` metric is deprecated The `io.confluent.kafka.server/cluster_active_link_count` is now deprecated. Please use the `io.confluent.kafka.server/cluster_link_count` metric instead. #### New metrics available in `/export` The following metrics are now available in the `/export` endpoint: * `io.confluent.kafka.server/request_bytes` * `io.confluent.kafka.server/response_bytes` * `io.confluent.kafka.server/cluster_link_destination_response_bytes` * `io.confluent.kafka.server/cluster_link_source_response_bytes` * `io.confluent.kafka.server/cluster_link_count` * `io.confluent.kafka.server/cluster_link_mirror_topic_count` * `io.confluent.kafka.server/cluster_link_mirror_topic_offset_lag` * `io.confluent.kafka.server/cluster_link_mirror_topic_bytes` ### 2022-10-17 #### API Version 1 is marked sunset All API Version 1 endpoints are no longer supported from 2022-10-17. API users should migrate to API [Version 2](#tag/Version-2). ### 2021-09-23 #### API Version 1 is now deprecated All API Version 1 endpoints are now deprecated and will be removed on 2022-04-04. API users should migrate to API [Version 2](#tag/Version-2). ### 2021-08-24 #### Metric-specific aggregation functions New metrics are being introduced that require alternative aggregation functions (e.g. `MAX`). When querying those metrics, using `agg: "SUM"` will return an error. It is recommended that clients **omit the `agg` field in the request** such that the required aggregation function for the specific metric is automatically applied on the backend. > Note: The initial version of Metrics API required clients to effectively hardcode `agg: "SUM"` > in all queries. In early 2021, the `agg` field was made optional, but many clients have not > been updated to omit the `agg` field. #### Cursor-based pagination for `/query` endpoint The `/query` endpoint now supports cursor-based pagination similar to the `/descriptors` and `/attributes` endpoints. ### 2021-02-10 #### API Version 2 is now Generally Available (GA) See the [Version 2](#tag/Version-2) section below for a detailed description of changes and migration guide. ### 2020-12-04 #### API Version 2 *(Preview)* Version 2 of the Metrics API is now available in Preview. See the [Version 2](#tag/Version-2) section below for a detailed description of changes. ### 2020-07-08 #### Correction for `active_connection_count` metric A bug in the `active_connection_count` metric that affected a subset of customers was fixed. Customers exporting the metric to an external monitoring system may observe a discontinuity between historical results and current results due to this one-time correction. ### 2020-04-01 This release includes the following changes from the preview release: #### New `format` request attribute The `/query` request now includes a `format` attribute which controls the result structuring in the response body. See the `/query` endpoint definition for more details. #### New `/available` endpoint The new `/available` endpoint allows determining which metrics are available for a set of resources (defined by labels). This endpoint can be used to determine which subset of metrics are currently available for a specific resource (e.g. a Confluent Cloud Kafka cluster). #### Metric type changes The `CUMULATIVE_(INT|DOUBLE)` metric type enumeration was changed to `COUNTER_(INT|DOUBLE)`. This was done to better align with OpenTelemetry conventions. In tandem with this change, several metrics that were improperly classified as `GAUGE`s were re-classified as `COUNTER`s. ### Metric name changes The `/delta` suffix has been removed from the following metrics: * `io.confluent.kafka.server/received_bytes/delta` * `io.confluent.kafka.server/sent_bytes/delta` * `io.confluent.kafka.server/request_count/delta` ### 2020-09-15 #### Retire `/available` endpoint The `/available` endpoint (which was in _Preview_ status) has been removed from the API. The `/descriptors` endpoint can still be used to determine the universe of available metrics for Metrics API. **The legacy metric names are deprecated and will stop functioning on 2020-07-01.** ## API Lifecycle Policy The following status labels are applicable to APIs, features, and SDK versions, based on the current support status of each: * **Early Access** – May change at any time. Not recommended for production usage. Not officially supported by Confluent. Intended for user feedback only. Users must be granted explicit access to the API by Confluent. * **Preview** – Unlikely to change between Preview and General Availability. Not recommended for production usage. Officially supported by Confluent for non-production usage. For Closed Previews, users must be granted explicit access to the API by Confluent. * **Generally Available (GA)** – Will not change at short notice. Recommended for production usage. Officially supported by Confluent for non-production and production usage. * **Deprecated** – No longer supported. Will be removed in the future at the announced date. Use is discouraged and migration following the upgrade guide is recommended. * **Sunset** – Removed, and no longer supported or available. Resources, operations, and individual fields in the OpenAPI spec will be annotated with `x-lifecycle-stage`, `x-deprecated-at`, and `x-sunset-at`. These annotations will appear in the corresponding API Reference Documentation. An API is "Generally Available" unless explicitly marked otherwise. ## Compatibility Policy Confluent APIs are governed by Confluent Cloud Upgrade Policy in which we will make backward incompatible changes and deprecations approximately once per year, and will provide 180 days notice via email to all registered Confluent Cloud users. ### Backward Compatibility > *An API version is backwards-compatible if a program written against the previous version of > the API will continue to work the same way, without modification, against this version of the > API.* Confluent considers the following changes to be backwards-compatible: * Adding new API resources. * Adding new optional parameters to existing API requests (e.g., query string or body). * Adding new properties to existing API responses. * Changing the order of properties in existing API responses. * Changing the length or format of object IDs or other opaque strings. * Unless otherwise documented, you can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If you're using MySQL, for example, you should store IDs in a `VARCHAR(255) COLLATE utf8_bin` column. * This includes adding or removing fixed prefixes (such as `lkc-` on kafka cluster IDs). * This includes API keys, API tokens, and similar authentication mechanisms. * This includes all strings described as "opaque" in the docs, such as pagination cursors. * Omitting properties with null values from existing API responses. ### Client Responsibilities * Resource and rate limits, and the default and maximum sizes of paginated data **are not** considered part of the API contract and may change (possibly dynamically). It is the client's responsibility to read the road signs and obey the speed limit. * If a property has a primitive type and the API documentation does not explicitly limit its possible values, clients **must not** assume the values are constrained to a particular set of possible responses. * If a property of an object is not explicitly declared as mandatory in the API, clients **must not** assume it will be present. * A resource **may** be modified to return a "redirection" response (e.g. `301`, `307`) instead of directly returning the resource. Clients **must** handle HTTP-level redirects, and respect HTTP headers (e.g. `Location`). ## Deprecation Policy Confluent will announce deprecations at least 180 days in advance of a breaking change and we will continue to maintain the deprecated APIs in their original form during this time. Exceptions to this policy apply in case of critical security vulnerabilities or functional defects. ### Communication When a deprecation is announced, the details and any relevant migration information will be available on the following channels: * Publication in the [API Changelog](#section/Versioning/Changelog) * Lifecycle, deprecation and "x-deprecated-at" annotations in the OpenAPI spec * Announcements on the Developer Blog, Community Slack (join!), Google Group, the @ConfluentInc twitter account, and similar channels * Enterprise customers may receive information by email to their specified Confluent contact, if applicable. # Object Model The object model for the Metrics API is designed similarly to the [OpenTelemetry](https://opentelemetry.io/) standard. ## Metrics A _metric_ is a numeric attribute of a resource, measured at a specific point in time, labeled with contextual metadata gathered at the point of instrumentation. There are two types of metrics: * `GAUGE`: An instantaneous measurement of a value. Gauge metrics are implicitly averaged when aggregating over time. > Example: `io.confluent.kafka.server/retained_bytes` * `COUNTER`: The count of occurrences in a _single (one minute) sampling interval_ (unless otherwise stated in the metric description). Counter metrics are implicitly summed when aggregating over time. > Example: `io.confluent.kafka.server/received_bytes` The list of metrics and their labels is available at [/docs/descriptors](/docs/descriptors). ## Resources A _resource_ represents an entity against which metrics are collected. For example, a Kafka cluster, a Kafka Connector, a ksqlDB application, etc. Each metric _descriptor_ is associated with one or more resource _descriptors_, representing the resource types to which that metric can apply. A metric _data point_ is associated with a single resource _instance_, identified by the resource labels on that metric data point. For example, metrics emitted by Kafka Connect are associated to the `connector` resource type. Data points for those metrics include resource labels identifying the specific `connector` instance that emitted the metric. The list of resource types and labels are discoverable via the `/descriptors/resources` endpoint. ## Labels A _label_ is a key-value attribute associated with a metric data point. Labels can be used in queries to filter or group the results. Labels must be prefixed when used in queries: * `metric.