--- title: List metric SQL models 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 metric SQL models{% #list-metric-sql-models %} {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | ---------------------------------------------------------------------- | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/experiments/metric-sql-models | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/experiments/metric-sql-models | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/experiments/metric-sql-models | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/experiments/metric-sql-models | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/experiments/metric-sql-models | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/experiments/metric-sql-models | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/experiments/metric-sql-models | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/experiments/metric-sql-models | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/experiments/metric-sql-models | ### Overview List metric SQL models. Returns a paginated list of the SQL models that metrics are defined on 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 metric_count and experiment_count, which cost 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. | | sort | string | Sort field: name, created_at, updated_at, metric_count, or experiment_count. A single field only; a comma-separated list is rejected. Prefix with `-` for descending (for example, `-created_at`). Defaults to created_at descending. | ### Response {% tab title="200" %} OK {% tab title="Model" %} List of metric SQL model resources with pagination information. | Parent field | Field | Type | Description | | ------------- | ------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | Resources returned in this response. | | data | attributes | object | Details of the metric SQL model. | | attributes | certified_at | date-time | Time when this resource was certified. | | attributes | created_at | date-time | Time when this resource was created. | | attributes | date_partition_column | string | SQL column used to partition the source data by date. | | attributes | description | string | Text that explains the metric SQL model. | | attributes | event_count_measure_id | string | Read-only measure ID. Pass it as warehouse_metric_measure.id when the metric operation is count. | | attributes | experiment_count | int64 | Number of experiments that reference this resource. | | attributes | is_certified | boolean | Whether this resource has been certified. | | attributes | measures | [object] | Measures available from the SQL model's result columns. | | measures | column_name | string | Name of the SQL result column that supplies this measure. | | measures | column_type | enum | Data type of a column in the SQL model. Allowed enum values: `STRING,INTEGER,FLOAT,BOOLEAN,DATE,TIMESTAMP` | | measures | description | string | Text that explains the measure. | | measures | id | string | ID of the measure. | | measures | migration_metadata | | Metadata retained for resources imported from another system. | | measures | name | string | Display name of the measure. | | attributes | metric_count | int64 | Number of metrics that use this SQL model. | | attributes | migration_metadata | | Metadata retained for resources imported from another system. | | attributes | name | string | Display name of the metric SQL model. | | attributes | properties | [object] | Property columns exposed by the SQL model. | | properties | column_name | string | Name of the SQL result column that supplies this measure. | | properties | column_type | enum | Data type of a column in the SQL model. Allowed enum values: `STRING,INTEGER,FLOAT,BOOLEAN,DATE,TIMESTAMP` | | properties | description | string | Text that explains the measure. | | properties | id | string | ID of the measure. | | properties | migration_metadata | | Metadata retained for resources imported from another system. | | properties | name | string | Display name of the measure. | | attributes | sql | string | SQL query that produces the model's source data. | | attributes | subject_types | [object] | Subject types mapped to columns in the SQL model. | | subject_types | column_name | string | Name of the SQL result column that identifies subjects of this type. | | subject_types | subject_type_id | string | ID of the subject type used by this configuration. | | subject_types | unique_subject_count_measure_id | string | Read-only measure ID. Pass it as warehouse_metric_measure.id when the metric operation is `uniqueSubjects`. | | attributes | timestamp_column | string | SQL column that supplies the event timestamp. | | attributes | updated_at | date-time | Time when this resource was last updated. | | data | id [*required*] | uuid | ID of the metric SQL model. | | data | type [*required*] | enum | Metric SQL models resource type. Allowed enum values: `metric-sql-models` | | | 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", "event_count_measure_id": "550e8400-e29b-41d4-a716-446655440024", "is_certified": false, "measures": [ { "column_name": "revenue", "column_type": "FLOAT", "id": "550e8400-e29b-41d4-a716-446655440021", "name": "revenue" } ], "name": "Order facts", "properties": [ { "column_name": "item_type", "column_type": "STRING", "id": "550e8400-e29b-41d4-a716-446655440023", "name": "item_type" } ], "sql": "SELECT user_id, order_id, item_type, revenue, created_at FROM analytics.orders", "subject_types": [ { "column_name": "user_id", "subject_type_id": "550e8400-e29b-41d4-a716-446655440010", "unique_subject_count_measure_id": "550e8400-e29b-41d4-a716-446655440022" } ], "timestamp_column": "created_at", "updated_at": "2024-01-01T12:00:00Z" }, "id": "550e8400-e29b-41d4-a716-446655440020", "type": "metric-sql-models" } ] } ``` {% /tab %} {% /tab %} {% tab title="400" %} Invalid query parameter: bad page[offset]/page[limit], unknown sort field, or unknown include value. {% 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/metric-sql-models" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" {% /tab %}