List metric definitions

GET {{baseUrl}}/api/-/pulse/definitions?order_by=<string>&view=DEFINITION_VIEW_FULL&number_of_metrics=<long>&page_size=<integer>&filter=<string>&metric_id=<string>&page_token=<string>

Lists the metric definitions configured for a site or, optionally, the details and definition for a specific metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insightdefinitionsmetrics:read
Access Scopes Overview: Cloud

Request Params

• DEFINITION_VIEW_BASIC - Return only the specified metric definition.

• DEFINITION_VIEW_FULL - Return the metric definition and the specified number of metrics.

• DEFINITION_VIEW_DEFAULT - Return the metric definition and the default metric. | | number_of_metrics | string | | (Required if view is DEFINITION_VIEW_FULL) The number of metrics to return. | | page_size | string | | description: |- Specifies the number of results in a paged response.

  Example:

  > GET .../subscriptions?pageSize=50

  Combining Path Parameters: A page_size expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression.

  <a href='https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm&#39; target='_blank'>Learn more about paginating the response</a>. required: false | | filter | string | | | | metric_id | string | | If a metric LUID is specified, only return the definition that is related to the metric, and the details of the metric. | | page_token | string | | Specifies the page of items to be returned from a requested list. The value of page_token for the next page of returns is found in the next_page_token of the current response. If there are no further items to return, the value of next_page_token will be empty.

Example:

> GET .../definitions?pageToken={next_page_value}

Combining Path Parameters: A page_token expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression.

<a href='https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm&#39; target='_blank'>Learn more about paginating the response</a>. |

HEADERS

RESPONSES

status: OK

{"definitions":{"type":"array","items":{"properties":{"metadata":{"properties":{"name":{"type":"string","description":"The name of the definition.","default":"\u003cstring\u003e"},"description":{"type":"string","description":"The description of the definition.","default":"\u003cstring\u003e"},"id":{"type":"string","description":"The LUID of the definition.","default":"\u003cstring\u003e"},"schema_version":{"type":"string","description":"The version of the schema of the definition. Current version is 1.0.0.","default":"\u003cstring\u003e"},"definition_version":{"type":"integer","description":"The version of the definition. Increments every time the definition is updated.","format":"int64","default":"\u003clong\u003e"}},"type":"object"},"specification":{"properties":{"datasource":{"properties":{"id":{"type":"string","description":"The LUID for the datasource for a definition.","default":"\u003cstring\u003e"}},"type":"object"},"basic_specification":{"properties":{"measure":{"properties":{"field":{"type":"string","description":"The data source field of the measure of the metric.","default":"\u003cstring\u003e"},"aggregation":{"type":"string","description":"\u003cbr/\u003eThe method used to aggregate the values of the measured data source field.","enum":["AGGREGATION_UNSPECIFIED","AGGREGATION_SUM","AGGREGATION_AVERAGE","AGGREGATION_MEDIAN","AGGREGATION_MAX","AGGREGATION_MIN","AGGREGATION_COUNT","AGGREGATION_COUNT_DISTINCT"]}},"type":"object"},"time_dimension":{"properties":{"field":{"type":"string","description":"The data source field used for the time dimension of the metric.","default":"\u003cstring\u003e"}},"type":"object"},"filters":{"type":"array","items":{"properties":{"field":{"type":"string","description":"_(Required)_ The data source field that contains the values of metric filter options.","default":"\u003cstring\u003e"},"operator":{"type":"string","description":"_(Required)_ The operator of the filter. Determines if the filter includes or excludes the specified categorical values.","enum":["OPERATOR_UNSPECIFIED","OPERATOR_EQUAL","OPERATOR_NOT_EQUAL"]},"categorical_values":{"type":"array","description":"_(Required)_ An array listing the values of the field to be operated on when the filter is applied to the metric data. The type of each member can be one of string, boolean, or null.","items":{"properties":{"string_value":{"type":"string","description":"The string value of the categorical value.","default":"\u003cstring\u003e"},"bool_value":{"type":"boolean","description":"The boolean value of the categorical value.","default":"\u003cboolean\u003e"},"null_value":{"type":"string","description":"The null value of the categorical value.","default":"\u003cstring\u003e"}},"type":"object"}}},"type":"object"}}},"type":"object"},"viz_state_specification":{"properties":{"viz_state_string":{"type":"string","description":" This is a Base64 encoded string, typically generated via the advanced option in the Tableau user interface.","default":"\u003cstring\u003e"}},"type":"object"},"is_running_total":{"type":"boolean","description":"If true, metrics related to a definition have a running total. If false, then totals are only for the defined time period of the measure. Defaults to false.","default":"\u003cboolean\u003e"}},"type":"object"},"extension_options":{"properties":{"allowed_dimensions":{"type":"array","items":{"type":"string","default":"\u003cstring\u003e"},"description":"_(Required)_ Specifies which data source dimensions can be used  as filters by metrics created using the definition.  Values included are a comma separated list of data source column names."},"allowed_granularities":{"type":"array","items":{"type":"string","description":"_(Required)_ Specifies the span of time time that can be used to calculate metrics created using the definition.","enum":["GRANULARITY_UNSPECIFIED","GRANULARITY_BY_YEAR","GRANULARITY_BY_QUARTER","GRANULARITY_BY_MONTH","GRANULARITY_BY_WEEK","GRANULARITY_BY_DAY"]}}},"type":"object"},"metrics":{"type":"array","items":{"properties":{"id":{"type":"string","description":"The LUID of the metric.","default":"\u003cstring\u003e"},"specification":{"properties":{"filters":{"type":"array","items":{"properties":{"field":{"type":"string","description":"_(Required)_ The data source field that contains the values of metric filter options.","default":"\u003cstring\u003e"},"operator":{"type":"string","description":"_(Required)_ The operator of the filter. Determines if the filter includes or excludes the specified categorical values.","enum":["OPERATOR_UNSPECIFIED","OPERATOR_EQUAL","OPERATOR_NOT_EQUAL"]},"categorical_values":{"type":"array","description":"_(Required)_ An array listing the values of the field to be operated on when the filter is applied to the metric data. The type of each member can be one of string, boolean, or null.","items":{"properties":{"string_value":{"type":"string","description":"The string value of the categorical value.","default":"\u003cstring\u003e"},"bool_value":{"type":"boolean","description":"The boolean value of the categorical value.","default":"\u003cboolean\u003e"},"null_value":{"type":"string","description":"The null value of the categorical value.","default":"\u003cstring\u003e"}},"type":"object"}}},"type":"object"}},"measurement_period":{"properties":{"granularity":{"type":"string","description":"_(Required)_ The time period used to aggregate the metric.","enum":["GRANULARITY_UNSPECIFIED","GRANULARITY_BY_YEAR","GRANULARITY_BY_QUARTER","GRANULARITY_BY_MONTH","GRANULARITY_BY_WEEK","GRANULARITY_BY_DAY"]},"range":{"type":"string","description":"Options for how to define the period that measures are aggregated in.\u003cbr/\u003e\u003cul\u003e\u003cli\u003e`RANGE_CURRENT_PARTIAL` - use an aggregation of the measures in the current period up till now.\u003c/li\u003e\u003cli\u003e`RANGE_LAST_COMPLETE` - use an aggregation of the measures up till the end of the last complete period.\u003c/li\u003e\u003c/ul\u003e","enum":["RANGE_UNSPECIFIED","RANGE_CURRENT_PARTIAL","RANGE_LAST_COMPLETE"]}},"type":"object"},"comparison":{"properties":{"comparison":{"type":"string","description":"The configuration of the period of metric values being compared.","enum":["TIME_COMPARISON_UNSPECIFIED","TIME_COMPARISON_NONE","TIME_COMPARISON_PREVIOUS_PERIOD","TIME_COMPARISON_YEAR_AGO_PERIOD"]}},"type":"object"}},"type":"object"},"definition_id":{"type":"string","description":"The LUID of the definition that the metric is related to.","default":"\u003cstring\u003e"},"is_default":{"type":"boolean","description":"If true, the metric is the default metric that is created for it's definition. If false, the metric was created by a user or programmatically. Default metrics can't be deleted unless their definition is deleted.","default":"\u003cboolean\u003e"},"schema_version":{"type":"string","description":"The version of the schema of the metric. The current version is 1.0.0.","default":"\u003cstring\u003e"}},"type":"object"}},"total_metrics":{"type":"integer","description":"The total number of metrics in the definition.","format":"int64","default":"\u003clong\u003e"},"representation_options":{"properties":{"type":{"type":"string","description":"The number format type of the definition.","enum":["NUMBER_FORMAT_TYPE_UNSPECIFIED","NUMBER_FORMAT_TYPE_NUMBER","NUMBER_FORMAT_TYPE_PERCENT","NUMBER_FORMAT_TYPE_CURRENCY"]},"number_units":{"properties":{"singular_noun":{"type":"string","description":"The singular noun to use for the number unit.","default":"\u003cstring\u003e"},"plural_noun":{"type":"string","description":"The plural noun to use for the number unit.","default":"\u003cstring\u003e"}},"type":"object"},"sentiment_type":{"type":"string","description":"Whether the favorable direction of the metric to increase or decrease, or is neutral.","enum":["SENTIMENT_TYPE_UNSPECIFIED","SENTIMENT_TYPE_NONE","SENTIMENT_TYPE_UP_IS_GOOD","SENTIMENT_TYPE_DOWN_IS_GOOD"]},"row_level_id_field":{"properties":{"identifier_col":{"type":"string","description":"The data source column that contains the `identifier_label` of a row whose values will be aggregated for the metric.","default":"\u003cstring\u003e"},"identifier_label":{"type":"string","description":"The value in `identifier_col` column that causes the row containing the label to be aggregated as part of the metric.","default":"\u003cstring\u003e"}},"type":"object"},"row_level_entity_names":{"properties":{"entity_name_singular":{"type":"string","description":"The singular form of the expression describing the row level dimension of a data source.","default":"\u003cstring\u003e"},"entity_name_plural":{"type":"string","description":"The plural form of the expression describing the row level dimension of a data source.","default":"\u003cstring\u003e"}},"type":"object"}},"type":"object"},"insights_options":{"properties":{"settings":{"type":"array","items":{"properties":{"type":{"type":"string","description":"The type of the insight setting.","enum":["INSIGHT_TYPE_UNSPECIFIED","INSIGHT_TYPE_RISKY_MONOPOLY","INSIGHT_TYPE_TOP_DRIVERS","INSIGHT_TYPE_RECORD_LEVEL_OUTLIERS","INSIGHT_TYPE_CURRENT_TREND","INSIGHT_TYPE_NEW_TREND","INSIGHT_TYPE_TOP_DIMENSION_MEMBER_MOVERS","INSIGHT_TYPE_METRIC_FORECAST","INSIGHT_TYPE_BOTTOM_CONTRIBUTORS","INSIGHT_TYPE_TOP_DETRACTORS"]},"disabled":{"type":"boolean","description":"Determines whether or not the insight setting is disabled. Defaults to false.","default":"\u003cboolean\u003e"}},"type":"object"}}},"type":"object"}},"type":"object"}},"next_page_token":"\u003cstring\u003e","total_available":"\u003cinteger\u003e","offset":"\u003cinteger\u003e"}