# Audience segment metrics {% hint style="info" %} **Important**\ \ If you're using the new **segment metrics** system, please check the dedicated documentation page for up-to-date information: [segment metrics documentation](https://userguides.mediarithmics.io/audience/segments/deep-dive-on-the-segment-page/metrics-panel) {% endhint %} Audience segment metrics are a way to offer **custom metrics on segments** to users. They are visible on the segment listing and segment details pages. The value of each metric is calculated regularly for each segment and saved to offer a historic view of its values. ![Segment details page on a datamart with 2 custom audience segment metrics](/files/-MTKbA8sDkL5nn7OrJWV) {% hint style="success" %} The total number of UserPoint is always calculated and displayed, even if there are no custom metrics. {% endhint %} ![A segment view without custom metrics](/files/-MTKamLVw7tWnD9y8NS9) ## How to configure metrics Audience segment metrics are configured per datamart and built on top of OTQL queries. Each metric has: * An associated [OTQL Query](/querying-your-data/otql-queries.md#managing-queries) * A technical name, possible values being `emails`, `user_accounts`, `desktop_cookie_ids`, `mobile_cookie_ids` or `mobile_ad_ids`. You can't use a custom value, and each of these values can only be used once per datamart. * A display name shown in the UI * A status: `DRAFT`, `LIVE` or `ARCHIVED`. * An icon, from a set of possible icons. {% hint style="info" %} **The metrics calculate how many UserPoint in the segment have at least one record. It doesn't count the number of records in the segment.** If you add a metric that counts the number of cookies and a UserPoint is associated with multiple cookies in the platform, it will be counted as only a +1 and not a +2. The metrics values will always be lower or equal to the number of UserPoint in the segment. {% endhint %} A metric goes from `DRAFT` status to `LIVE` and from `LIVE` status to `ARCHIVED`. You cannot republish an `ARCHIVED` metric. You can only remove it. ## Listing existing metrics `GET` `https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics` #### Path Parameters | Name | Type | Description | | ---------- | ------ | ---------------------- | | datamartId | string | The ID of the datamart | {% tabs %} {% tab title="200 " %} ```javascript { "status": "ok", "data": [ { "id": "1555", "datafarm_key": "DF_EU_2020_02", "datamart_id": "1509", "query_id": "50659", "technical_name": "user_accounts", "display_name": "User Profiles", "icon": "users", "status": "LIVE", "creation_date": 1613125152462, "last_modified_date": 1613125152462, "last_published_date": null }, { "id": "1558", "datafarm_key": "DF_EU_2020_02", "datamart_id": "1509", "query_id": "50659", "technical_name": "mobile_cookie_ids", "display_name": "User Profiles", "icon": "users", "status": "LIVE", "creation_date": 1613125314757, "last_modified_date": 1613125314757, "last_published_date": null }, { "id": "1566", "datafarm_key": "DF_EU_2020_02", "datamart_id": "1509", "query_id": "50659", "technical_name": "mobile_ad_ids", "display_name": "User Profiles 7", "icon": "users", "status": "ARCHIVED", "creation_date": 1613128930707, "last_modified_date": 1613128930707, "last_published_date": null }, { "id": "1569", "datafarm_key": "DF_EU_2020_02", "datamart_id": "1509", "query_id": "50659", "technical_name": "desktop_cookie_ids", "display_name": "User Profiles 4", "icon": "gears", "status": "LIVE", "creation_date": 1613129103522, "last_modified_date": 1613129103522, "last_published_date": null }, { "id": "1570", "datafarm_key": "DF_EU_2020_02", "datamart_id": "1509", "query_id": "50659", "technical_name": "desktop_cookie_ids", "display_name": "User Profiles 4", "icon": "gears", "status": "DRAFT", "creation_date": 1613129261878, "last_modified_date": 1613129261878, "last_published_date": null } ], "count": 5, "total": 5, "first_result": 0, "max_result": 50, "max_results": 50 } ``` {% endtab %} {% endtabs %} ## Create an audience metric `POST` `https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics` This creates a DRAFT metric. #### Path Parameters | Name | Type | Description | | ---------- | ------- | ---------------------- | | datamartId | integer | The ID of the datamart | #### Request Body | Name | Type | Description | | ---- | ------ | ----------------------------- | | Body | object | The metric you wish to create | {% tabs %} {% tab title="200 " %} ```javascript { "status": "ok", "data": { "id": "1571", "datafarm_key": "DF_EU_2020_02", "datamart_id": "1509", "query_id": "50659", "technical_name": "emails", "display_name": "User Profiles 7", "icon": "users", "status": "DRAFT", "creation_date": 1613130322659, "last_modified_date": 1613130322659, "last_published_date": null } } ``` {% endtab %} {% tab title="400 If values are not valid" %} ```javascript { "status": "error", "error": "Json object is not structured as expected", "error_code": "BAD_REQUEST_FORMAT", "error_id": "e18c26a1-7497-470d-8480-2bcb66fc8f16" } ``` {% endtab %} {% endtabs %} {% hint style="info" %} You must first [create an OTQL query,](/querying-your-data/otql-queries.md#creating-a-query) returning a number corresponding to your metric. As each datamart can have its very own schema, **those queries should be tested for each datamart (by API or in the Data Studio) and should return a number.** The configured query will be "merged" with the query of each segment to calculate the proper metric. Here are some common query examples: * `SELECT @count{id} FROM UserPoint WHERE agents{}` counts the number of UserPoint having at least 1 cookie or mobile ID (user agent) * `SELECT @count{id} FROM UserPoint WHERE profiles{}` counts the number of UserPoint having at least 1 profile * `SELECT @count{id} FROM UserPoint WHERE emails{}` counts the number of UserPoint having at least 1 email {% endhint %} Here is a sample body payload: ```javascript { "datamart_id": "<>", "query_id": "", "technical_name": "", "display_name": "User Profiles", "icon": "users" } ``` ## Activate the audience metric `POST` `https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics/:metricId/action` This action transitions the metric go from `DRAFT` to `LIVE`.status. Any existing metric in `LIVE` status with the same technical name is `ARCHIVED`. #### Path Parameters | Name | Type | Description | | ---------- | ------- | ------------------------------- | | datamartId | integer | The ID of the datamart | | metricId | integer | The ID of the metric to publish | #### Request Body | Name | Type | Description | | ---- | ------ | ----------------------- | | Body | object | { "action": "PUBLISH" } | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Remove an audience metric `DELETE` `https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics/:metricId` #### Path Parameters | Name | Type | Description | | ---------- | ------- | ------------------------------ | | datamartId | integer | The ID of the datamart | | metricId | integer | The ID of the metric to remove | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ## Limitations 1. Only five custom audience segment metrics per datamart are allowed—one per available technical name. 2. [@cardinality aggregations](/querying-your-data/otql-queries.md#aggregation-operations) are not supported in the queries. ## Available icons Each metric is associated with an icon taken from the following catalogue. ### Most used icons * display * users * email-inverted * phone ![](/files/-MTLAE6FrxsDSyHaPGBI) ### Other icons * adGroups * ads * automation * bell * bolt * check-rounded-inverted * check-rounded * check * chevron-right * chevron * close-big * close-rounded * close * code * creative * data * delete * display * dots * download * email-inverted * email * extend * filters * full-users * file * gears * goals-rounded * goals * image * info * laptop * library * magnifier * menu-close * minus * optimization * options * partitions * pause * pen * phone * play * plus * query * question * refresh * settings * smartphone * status * tablet * user * users * user-query * user-pixel * user-list * video * warning --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.mediarithmics.io/advanced-usages/audiences/audience-segment-metrics.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.