--- title: Tag Configuration Cardinality Estimator description: Returns the estimated cardinality for a metric with a given tag, percentile and number of aggregations configuration using Metrics without Limits™. breadcrumbs: Docs > API > Tag Configuration Cardinality Estimator --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Tag Configuration Cardinality Estimator ## v2 (latest) | Datadog site | API endpoint | | ----------------- | ----------------------------------------------------------------------- | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/metrics/{metric_name}/estimate | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/metrics/{metric_name}/estimate | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/metrics/{metric_name}/estimate | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/metrics/{metric_name}/estimate | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/metrics/{metric_name}/estimate | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/metrics/{metric_name}/estimate | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/metrics/{metric_name}/estimate | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/metrics/{metric_name}/estimate | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/metrics/{metric_name}/estimate | ### Overview Returns the estimated cardinality for a metric with a given tag, percentile and number of aggregations configuration using Metrics without Limits™. To compare current volumes across many metrics, use `GET /api/v2/metrics` with `include=metric_volumes` instead of calling this endpoint for each metric. A `404 Not Found` response means that no metric with this name exists in your organization. A `400 Bad Request` response means that a query parameter is invalid, or that the metric has no data in the queried window. For no data, the error message says so and names the window that was queried, which can differ from the requested one. ### Arguments #### Path Parameters | Field | Type | Description | | ------------------------ | ------ | ----------------------- | | metric_name [*required*] | string | The name of the metric. | #### Query Strings | Field | Type | Description | | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter[groups] | string | Comma-separated list of tag keys that the metric is configured to query with. For example: `filter[groups]=app,host`. | | filter[exclude_tags_mode] | boolean | When `true`, `filter[groups]` is treated as an exclude list instead of an include list. Defaults to `false`. | | filter[hours_ago] | integer | The number of hours of look back (from now) to estimate cardinality with. If unspecified, it defaults to 0 hours (the most recent data). Values below 0 return `400 Bad Request`. | | filter[num_aggregations] | integer | Deprecated. Number of aggregations has no impact on volume. | | filter[pct] | boolean | Deprecated. This query parameter has no effect on the estimate. | | filter[timespan_h] | integer | A window, in hours, from the look back to estimate cardinality with. The minimum and default is 1 hour. Smaller values return `400 Bad Request`. | ### Response {% tabs %} {% tab label="200" %} Success {% tabs %} {% tab label="Model" %} Response object that includes metric cardinality estimates. | Parent field | Field | Type | Description | | ------------ | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | data | object | Object for a metric cardinality estimate. | | data | attributes | object | Object containing the definition of a metric estimate attribute. | | attributes | estimate_type | enum | Estimate type based on the queried configuration. `count_or_gauge` is returned by default, and `distribution` is returned for distribution metrics. The `filter[pct]` query parameter has no effect on this value. Allowed enum values: `count_or_gauge`, `distribution`, `percentile`. Default: `count_or_gauge`. | | attributes | estimated_at | date-time | Timestamp when the cardinality estimate was requested. | | attributes | estimated_output_series | int64 | Estimated cardinality of the metric based on the queried configuration. | | data | id | string | The metric name for this resource. | | data | type | enum | The metric estimate resource type. Allowed enum values: `metric_cardinality_estimate`. Default: `metric_cardinality_estimate`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "estimate_type": "distribution", "estimated_at": "2022-04-27T09:48:37.463835Z", "estimated_output_series": 50 }, "id": "test.metric.latency", "type": "metric_cardinality_estimate" } } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} API error response. {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="403" %} API error response. {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="404" %} API error response. {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too Many Requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Path parameters export metric_name="dist.http.endpoint.request" # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/metrics/${metric_name}/estimate" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% tab label="Go" %} ```go // Tag Configuration Cardinality Estimator returns "Success" response package main import ( "context" "encoding/json" "fmt" "os" "github.com/DataDog/datadog-api-client-go/v2/api/datadog" "github.com/DataDog/datadog-api-client-go/v2/api/datadogV2" ) func main() { ctx := datadog.NewDefaultContext(context.Background()) ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN")) configuration := datadog.NewConfiguration() apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewMetricsApi(apiClient) resp, r, err := api.EstimateMetricsOutputSeries(ctx, "system.cpu.idle", *datadogV2.NewEstimateMetricsOutputSeriesOptionalParameters().WithFilterGroups("app,host").WithFilterNumAggregations(4)) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `MetricsApi.EstimateMetricsOutputSeries`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `MetricsApi.EstimateMetricsOutputSeries`:\n%s\n", responseContent) } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" go run "main.go" ``` {% /tab %} {% tab label="Java" %} ```java // Tag Configuration Cardinality Estimator returns "Success" response import com.datadog.api.client.ApiClient; import com.datadog.api.client.ApiException; import com.datadog.api.client.v2.api.MetricsApi; import com.datadog.api.client.v2.api.MetricsApi.EstimateMetricsOutputSeriesOptionalParameters; import com.datadog.api.client.v2.model.MetricEstimateResponse; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN")); MetricsApi apiInstance = new MetricsApi(defaultClient); try { MetricEstimateResponse result = apiInstance.estimateMetricsOutputSeries( "system.cpu.idle", new EstimateMetricsOutputSeriesOptionalParameters() .filterGroups("app,host") .filterNumAggregations(4)); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling MetricsApi#estimateMetricsOutputSeries"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" java "Example.java" ``` {% /tab %} {% tab label="Python" %} ```python """ Tag Configuration Cardinality Estimator returns "Success" response """ from os import environ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.metrics_api import MetricsApi configuration = Configuration() configuration.access_token = environ["DD_BEARER_TOKEN"] with ApiClient(configuration) as api_client: api_instance = MetricsApi(api_client) response = api_instance.estimate_metrics_output_series( metric_name="system.cpu.idle", filter_groups="app,host", filter_num_aggregations=4, ) print(response) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" python3 "example.py" ``` {% /tab %} {% tab label="Ruby" %} ```ruby # Tag Configuration Cardinality Estimator returns "Success" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.access_token = ENV["DD_BEARER_TOKEN"] end api_instance = DatadogAPIClient::V2::MetricsAPI.new opts = { filter_groups: "app,host", filter_num_aggregations: 4, } p api_instance.estimate_metrics_output_series("system.cpu.idle", opts) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" ruby "example.rb" ``` {% /tab %} {% tab label="Rust" %} ```rust // Tag Configuration Cardinality Estimator returns "Success" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_metrics::EstimateMetricsOutputSeriesOptionalParams; use datadog_api_client::datadogV2::api_metrics::MetricsAPI; #[tokio::main] async fn main() { let configuration = datadog::Configuration::new(); let api = MetricsAPI::with_config(configuration); let resp = api .estimate_metrics_output_series( "system.cpu.idle".to_string(), EstimateMetricsOutputSeriesOptionalParams::default() .filter_groups("app,host".to_string()) .filter_num_aggregations(4), ) .await; if let Ok(value) = resp { println!("{:#?}", value); } else { println!("{:#?}", resp.unwrap_err()); } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: ```bash DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ``` {% /tab %} {% tab label="TypeScript" %} ```typescript /** * Tag Configuration Cardinality Estimator returns "Success" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration({ authMethods: { AuthZ: { accessToken: process.env.DD_BEARER_TOKEN as string, }, }, }); const apiInstance = new v2.MetricsApi(configuration); const params: v2.MetricsApiEstimateMetricsOutputSeriesRequest = { metricName: "system.cpu.idle", filterGroups: "app,host", filterNumAggregations: 4, }; apiInstance .estimateMetricsOutputSeries(params) .then((data: v2.MetricEstimateResponse) => { console.log( "API called successfully. Returned data: " + JSON.stringify(data) ); }) .catch((error: any) => console.error(error)); ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" npx tsx "example.ts" ``` {% /tab %} {% /tabs %}