# 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.
{% hint style="success" %}
The total number of UserPoint is always calculated and displayed, even if there are no custom metrics.
{% endhint %}
## 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](https://developer.mediarithmics.io/querying-your-data/otql-queries#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,](https://developer.mediarithmics.io/querying-your-data/otql-queries#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](https://developer.mediarithmics.io/querying-your-data/otql-queries#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
### 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