--- title: List metrics description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Experiments --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} # List metrics{% #list-metrics %} {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------ | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/experiments/metrics | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/experiments/metrics | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/experiments/metrics | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/experiments/metrics | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/experiments/metrics | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/experiments/metrics | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/experiments/metrics | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/experiments/metrics | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/experiments/metrics | ### Overview List metrics. Returns a paginated list of the experiment metrics defined for the organization. This endpoint requires the `product_analytics_metrics_read` permission. OAuth apps require the `product_analytics_metrics_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#experiments) to access this endpoint. ### Arguments #### Query Strings | Name | Type | Description | | ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | include | array | Optional fields to include. Repeat this parameter to request several fields. `counts` adds experiment_count on each metric, which costs an extra aggregate query. | | page[limit] | integer | Maximum number of results to return. Defaults to 25 when omitted, and is capped at 50 (larger values are clamped to 50). The response includes meta.page (with total) and pagination links. | | page[offset] | integer | Number of results to skip for pagination. Defaults to 0 when omitted. | | search | string | Find metrics whose names contain the search text, regardless of case. | | sort | string | Sort field: name, created_at, or updated_at. Prefix with `-` for descending (for example, `-created_at`). A single field only; a comma-separated list is rejected. Defaults to created_at descending. | ### Response {% tab title="200" %} OK {% tab title="Model" %} List of metric resources with pagination information. | Parent field | Field | Type | Description | | ------------------------ | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | Resources returned in this response. | | data | attributes | object | Details of the metric. | | attributes | certified_at | date-time | Time when this resource was certified. | | attributes | created_at | date-time | Time when this resource was created. | | attributes | data_source_type | enum | Source of the data used to calculate the metric. Allowed enum values: `DATADOG,DATADOG_REFERENCE_TABLE,CUSTOMER_WAREHOUSE,IMPORTED,UNKNOWN` | | attributes | denominator_aggregation | object | Source measure and aggregation settings for a metric value. | | denominator_aggregation | aging_threshold_days | int64 | Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. | | denominator_aggregation | datadog_metric_measure | object | Datadog source and query that supply values for the metric. | | datadog_metric_measure | column_name | string | Name of the Datadog event field used by this measure. | | datadog_metric_measure | column_type | string | Data type of the source column. | | datadog_metric_measure | filters | | Conditions used to select the metric's source data. | | datadog_metric_measure | name | string | Display name of the Datadog measure. | | datadog_metric_measure | query | string | Query used to retrieve the Datadog measure. | | datadog_metric_measure | source_definition_filter | | Filter applied to the Datadog source definition. | | datadog_metric_measure | source_subtype | string | Subtype of the Datadog data source. | | datadog_metric_measure | source_type | string | Type of Datadog data source used for the measure. | | denominator_aggregation | enable_aging_subject_filter | boolean | Whether to exclude subjects whose observation time is shorter than the aggregation window. | | denominator_aggregation | operation | string | Aggregation applied to the selected measure. | | denominator_aggregation | pipeline_column_suffix | string | Suffix used to identify this value in pipeline output columns. | | denominator_aggregation | property_filters | [array] | Filters applied to the metric aggregation. | | denominator_aggregation | threshold_aggregation_type | string | Aggregation used to evaluate the threshold. | | denominator_aggregation | threshold_breach_value | double | Value used to determine whether the threshold is breached. | | denominator_aggregation | threshold_comparison_operator | string | Comparison applied between the aggregated value and the threshold. | | denominator_aggregation | threshold_timeframe_dimension | string | Time unit used for the threshold evaluation window. | | denominator_aggregation | threshold_timeframe_value | double | Size of the threshold evaluation window. | | denominator_aggregation | timeframe_end_value | double | End of the aggregation window in the specified time unit. | | denominator_aggregation | timeframe_start_value | double | Start of the aggregation window in the specified time unit. | | denominator_aggregation | timeframe_unit | string | Time unit used for the aggregation window. | | denominator_aggregation | warehouse_metric_measure | object | Warehouse measure that supplies values for the metric. | | warehouse_metric_measure | id | string | ID of the measure. | | warehouse_metric_measure | pipeline_column_suffix | string | Suffix used to identify this value in pipeline output columns. | | denominator_aggregation | winsor_lower_fixed_value | double | Fixed lower bound used to cap metric values. | | denominator_aggregation | winsor_lower_percentile | double | Percentile used to determine the lower bound for capped metric values. | | denominator_aggregation | winsor_upper_fixed_value | double | Fixed upper bound used to cap metric values. | | denominator_aggregation | winsor_upper_percentile | double | Percentile used to determine the upper bound for capped metric values. | | denominator_aggregation | winsorization_strategy | string | Method used to cap extreme metric values. | | attributes | description | string | Text that explains the metric. | | attributes | desired_change | enum | Direction of metric change considered desirable. Allowed enum values: `METRIC_INCREASES,METRIC_DECREASES,UNKNOWN` | | attributes | experiment_count | int64 | Number of experiments that reference this resource. | | attributes | format_as_percent | boolean | Whether to display the metric value as a percentage. | | attributes | guardrail_cutoff_threshold | double | Threshold used when evaluating this metric as a guardrail. | | attributes | metric_type | enum | Type of metric calculation. Allowed enum values: `SIMPLE,RATIO,PERCENTILE,UNKNOWN` | | attributes | migration_metadata | | Metadata retained for resources imported from another system. | | attributes | name | string | Display name of the metric. | | attributes | numerator_aggregation | object | Source measure and aggregation settings for a metric value. | | numerator_aggregation | aging_threshold_days | int64 | Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. | | numerator_aggregation | datadog_metric_measure | object | Datadog source and query that supply values for the metric. | | datadog_metric_measure | column_name | string | Name of the Datadog event field used by this measure. | | datadog_metric_measure | column_type | string | Data type of the source column. | | datadog_metric_measure | filters | | Conditions used to select the metric's source data. | | datadog_metric_measure | name | string | Display name of the Datadog measure. | | datadog_metric_measure | query | string | Query used to retrieve the Datadog measure. | | datadog_metric_measure | source_definition_filter | | Filter applied to the Datadog source definition. | | datadog_metric_measure | source_subtype | string | Subtype of the Datadog data source. | | datadog_metric_measure | source_type | string | Type of Datadog data source used for the measure. | | numerator_aggregation | enable_aging_subject_filter | boolean | Whether to exclude subjects whose observation time is shorter than the aggregation window. | | numerator_aggregation | operation | string | Aggregation applied to the selected measure. | | numerator_aggregation | pipeline_column_suffix | string | Suffix used to identify this value in pipeline output columns. | | numerator_aggregation | property_filters | [array] | Filters applied to the metric aggregation. | | numerator_aggregation | threshold_aggregation_type | string | Aggregation used to evaluate the threshold. | | numerator_aggregation | threshold_breach_value | double | Value used to determine whether the threshold is breached. | | numerator_aggregation | threshold_comparison_operator | string | Comparison applied between the aggregated value and the threshold. | | numerator_aggregation | threshold_timeframe_dimension | string | Time unit used for the threshold evaluation window. | | numerator_aggregation | threshold_timeframe_value | double | Size of the threshold evaluation window. | | numerator_aggregation | timeframe_end_value | double | End of the aggregation window in the specified time unit. | | numerator_aggregation | timeframe_start_value | double | Start of the aggregation window in the specified time unit. | | numerator_aggregation | timeframe_unit | string | Time unit used for the aggregation window. | | numerator_aggregation | warehouse_metric_measure | object | Warehouse measure that supplies values for the metric. | | warehouse_metric_measure | id | string | ID of the measure. | | warehouse_metric_measure | pipeline_column_suffix | string | Suffix used to identify this value in pipeline output columns. | | numerator_aggregation | winsor_lower_fixed_value | double | Fixed lower bound used to cap metric values. | | numerator_aggregation | winsor_lower_percentile | double | Percentile used to determine the lower bound for capped metric values. | | numerator_aggregation | winsor_upper_fixed_value | double | Fixed upper bound used to cap metric values. | | numerator_aggregation | winsor_upper_percentile | double | Percentile used to determine the upper bound for capped metric values. | | numerator_aggregation | winsorization_strategy | string | Method used to cap extreme metric values. | | attributes | percentile_aggregation | object | Source measure and settings for a percentile metric. | | percentile_aggregation | datadog_metric_measure | object | Datadog source and query that supply values for the metric. | | datadog_metric_measure | column_name | string | Name of the Datadog event field used by this measure. | | datadog_metric_measure | column_type | string | Data type of the source column. | | datadog_metric_measure | filters | | Conditions used to select the metric's source data. | | datadog_metric_measure | name | string | Display name of the Datadog measure. | | datadog_metric_measure | query | string | Query used to retrieve the Datadog measure. | | datadog_metric_measure | source_definition_filter | | Filter applied to the Datadog source definition. | | datadog_metric_measure | source_subtype | string | Subtype of the Datadog data source. | | datadog_metric_measure | source_type | string | Type of Datadog data source used for the measure. | | percentile_aggregation | percentile | double | Percentile calculated from the selected measure. | | percentile_aggregation | pipeline_column_suffix | string | Suffix used to identify this value in pipeline output columns. | | percentile_aggregation | property_filters | [array] | Filters applied to the metric aggregation. | | percentile_aggregation | warehouse_metric_measure | object | Warehouse measure that supplies values for the metric. | | warehouse_metric_measure | id | string | ID of the measure. | | warehouse_metric_measure | pipeline_column_suffix | string | Suffix used to identify this value in pipeline output columns. | | attributes | reference_url | string | URL with supporting information about the metric. | | attributes | updated_at | date-time | Time when this resource was last updated. | | data | id [*required*] | uuid | ID of the metric. | | data | type [*required*] | enum | The metric resource type. Allowed enum values: `metrics` | | | links | object | Links for navigating a paginated result set. | | links | first | string | URL of the first page of results. | | links | last | string | URL of the last page of results. | | links | next | string | URL of the next page of results. | | links | prev | string | URL of the previous page of results. | | links | self | string | URL of the current page of results. | | | meta | object | Pagination information for a list response. | | meta | page | object | Result counts and offsets for a page of results. | | page | first_offset | int64 | Offset of the first page of results. | | page | last_offset | int64 | Offset of the last page of results. | | page | limit | int64 | Maximum number of results returned in one page. | | page | next_offset | int64 | Offset of the next page of results. | | page | offset | int64 | Number of results skipped before this page. | | page | prev_offset | int64 | Offset of the previous page of results. | | page | total | int64 | Total number of matching results across all pages. | | page | type | string | Pagination method used for this result set. | {% /tab %} {% tab title="Example" %} ```json { "data": [ { "attributes": { "created_at": "2024-01-01T12:00:00Z", "data_source_type": "CUSTOMER_WAREHOUSE", "description": "Share of sessions that reach the order confirmation page", "desired_change": "METRIC_INCREASES", "format_as_percent": true, "metric_type": "SIMPLE", "name": "Checkout conversion", "numerator_aggregation": { "operation": "sum", "pipeline_column_suffix": "agg001", "timeframe_start_value": 0, "warehouse_metric_measure": { "id": "550e8400-e29b-41d4-a716-446655440021", "pipeline_column_suffix": "rev001" } }, "reference_url": "", "updated_at": "2024-01-01T12:00:00Z" }, "id": "550e8400-e29b-41d4-a716-446655440002", "type": "metrics" } ] } ``` {% /tab %} {% /tab %} {% tab title="400" %} Invalid query parameter: bad page[offset]/page[limit], or unknown sort field. {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="401" %} Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session). {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Authenticated caller lacks the product_analytics_metrics_read permission. {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \# Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" \# Curl command curl -X GET "https://api.datadoghq.com/api/v2/experiments/metrics" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ##### ```python """ List metrics returns "OK" response """ from os import environ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.experiments_api import ExperimentsApi configuration = Configuration() configuration.access_token = environ["DD_BEARER_TOKEN"] with ApiClient(configuration) as api_client: api_instance = ExperimentsApi(api_client) response = api_instance.list_metrics() 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: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" python3 "example.py" ##### ```ruby # List metrics returns "OK" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.access_token = ENV["DD_BEARER_TOKEN"] end api_instance = DatadogAPIClient::V2::ExperimentsAPI.new p api_instance.list_metrics() ``` #### 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: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" rb "example.rb" ##### ```go // List metrics returns "OK" 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.NewExperimentsApi(apiClient) resp, r, err := api.ListMetrics(ctx, *datadogV2.NewListMetricsOptionalParameters()) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `ExperimentsApi.ListMetrics`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `ExperimentsApi.ListMetrics`:\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: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" go run "main.go" ##### ```java // List metrics returns "OK" response import com.datadog.api.client.ApiClient; import com.datadog.api.client.ApiException; import com.datadog.api.client.v2.api.ExperimentsApi; import com.datadog.api.client.v2.model.ExperimentsMetricV2DTOArray; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN")); ExperimentsApi apiInstance = new ExperimentsApi(defaultClient); try { ExperimentsMetricV2DTOArray result = apiInstance.listMetrics(); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ExperimentsApi#listMetrics"); 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: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" java "Example.java" ##### ```rust // List metrics returns "OK" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_experiments::ExperimentsAPI; use datadog_api_client::datadogV2::api_experiments::ListMetricsOptionalParams; #[tokio::main] async fn main() { let configuration = datadog::Configuration::new(); let api = ExperimentsAPI::with_config(configuration); let resp = api.list_metrics(ListMetricsOptionalParams::default()).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: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run {% /tab %}