> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/plan-and-integrate/set-up-the-environment/set-up-segment-metrics.md).

# Segment metrics

Choose the counts your teams see on every segment, on top of the UserPoint total.

## Your goal

Add the counts that matter to your teams - reachable emails, known accounts, addressable cookies or mobile IDs - to every segment in a datamart, so nobody has to run a query to answer "how many of these users can I actually reach?".

## Expected outcome

Segment listing and segment detail pages show your custom metrics alongside the UserPoint total, and the values are refreshed and kept as a history.

## What a segment metric is

A **segment metric** is a custom metric offered on segments across a datamart. Metrics are visible on the segment listing and on segment detail pages, and the value of each metric is calculated regularly for every segment and saved, which gives you a historic view of how it evolves.

Segment metrics are configured **per datamart** and built on top of [OTQL](/setup-and-monitor/operate-and-monitor/query-your-datamart/otql.md) queries.

{% hint style="warning" %}
This page documents the **API-based** segment metrics system. A newer system, configured from **Settings > Datamart > Datamarts > Segment Metrics** in the interface, is documented in the `Audience & Activation` section under *Build your audiences › Segment reference › Segment capabilities › Segment metrics*. The two differ in what a metric counts, in the statuses a metric can take, and in how many can be active at once - check which one your organisation uses before configuring anything.
{% endhint %}

{% hint style="success" %}
The total number of UserPoints is always calculated and displayed, even when no custom metric is configured.
{% endhint %}

{% hint style="info" %}
A metric counts **how many UserPoints in the segment have at least one matching record** - not how many records the segment contains. If you add a metric counting cookies and a UserPoint has several cookies, it counts as +1, not +2. Metric values are therefore always lower than or equal to the number of UserPoints in the segment.
{% endhint %}

## What each metric is made of

| Field              | What it holds                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query**          | An OTQL query returning a number.                                                                                                                                               |
| **Technical name** | One of `emails`, `user_accounts`, `desktop_cookie_ids`, `mobile_cookie_ids`, `mobile_ad_ids`. Custom values are not allowed, and each value can be used only once per datamart. |
| **Display name**   | The label shown in the interface.                                                                                                                                               |
| **Status**         | `DRAFT`, `LIVE`, or `ARCHIVED`.                                                                                                                                                 |
| **Icon**           | Chosen from a fixed catalogue. Commonly used icons are `display`, `users`, `email-inverted`, and `phone`.                                                                       |

## Set up a metric

{% stepper %}
{% step %}

### Write and save the OTQL query

The query must return a number. Because every datamart has its own schema, test the query on the datamart concerned - in the Query Tool or by API - before you use it.

Common shapes:

```sql
-- UserPoints having at least one cookie or mobile ID
SELECT @count{id} FROM UserPoint WHERE agents{}

-- UserPoints having at least one profile
SELECT @count{id} FROM UserPoint WHERE profiles{}

-- UserPoints having at least one email
SELECT @count{id} FROM UserPoint WHERE emails{}
```

The configured query is merged with the query of each segment to produce that segment's value, so write it as a datamart-wide count, not as a count for one segment.
{% endstep %}

{% step %}

### Create the metric

Metrics are created in `DRAFT` status:

```
POST https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics
```

```json
{
    "datamart_id": "<DATAMART ID>",
    "query_id": "<OTQL QUERY ID>",
    "technical_name": "<TECHNICAL_NAME>",
    "display_name": "User Profiles",
    "icon": "users"
}
```

{% endstep %}

{% step %}

### Publish it

Publishing transitions the metric from `DRAFT` to `LIVE`. Any existing `LIVE` metric with the same technical name is archived automatically.

```
POST https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics/:metricId/action
```

```json
{ "action": "PUBLISH" }
```

{% endstep %}

{% step %}

### Check it on a segment

Open any segment in the datamart. The metric should appear next to the UserPoint total once values have been calculated.
{% endstep %}
{% endstepper %}

Existing metrics can be listed with `GET /v1/datamarts/:datamartId/audience_segment_metrics`, and removed with `DELETE /v1/datamarts/:datamartId/audience_segment_metrics/:metricId`.

## Lifecycle

A metric goes from `DRAFT` to `LIVE`, and from `LIVE` to `ARCHIVED`. An `ARCHIVED` metric cannot be republished - it can only be removed.

```mermaid
stateDiagram-v2
    [*] --> DRAFT: create
    DRAFT --> LIVE: publish
    LIVE --> ARCHIVED: superseded or archived
    ARCHIVED --> [*]: remove
```

## Limitations

* **Five custom metrics per datamart** at most - one per available technical name.
* `@cardinality` aggregations are not supported in metric queries.

See [Platform limits](/setup-and-monitor/plan-and-integrate/set-up-the-environment/platform-limits.md) for the other documented ceilings.

## Troubleshooting

| Symptom                               | Likely cause                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| The metric is rejected on creation    | The technical name is not one of the five allowed values, or it is already used by another metric on the datamart. |
| The metric shows no value             | The query does not return a number on this datamart's schema. Test it in the Query Tool first.                     |
| The value looks lower than expected   | Metrics count UserPoints having at least one record, not records.                                                  |
| Publishing removed an existing metric | Publishing a metric archives the `LIVE` metric that shares its technical name.                                     |

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Query your datamart</strong></td><td>Write and test the OTQL query behind a metric.</td><td><a href="/setup-and-monitor/operate-and-monitor/query-your-datamart.md">Query your datamart</a></td></tr><tr><td><strong>Platform limits</strong></td><td>The documented ceilings across the platform.</td><td><a href="/setup-and-monitor/plan-and-integrate/set-up-the-environment/platform-limits.md">Platform limits</a></td></tr><tr><td><strong>Standard segment builder</strong></td><td>The other datamart-level segmentation setup.</td><td><a href="/setup-and-monitor/plan-and-integrate/set-up-advanced-features/standard-segment-builder.md">Standard segment builder</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/plan-and-integrate/set-up-the-environment/set-up-segment-metrics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.