> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom metrics

> Define a metric once, such as add-to-cart rate or cost per lead, and use it on Ads, Reports, dashboards, and in AI chat. Every surface shows the same number.

A custom metric is a formula over ad metrics, such as `Meta adds to cart ÷ Link clicks`.
The workspace stores one definition. The Ads table, Reports cards, dashboards, share
links, [AI chat](/product/ai-chat), and the [MCP server](/datalyr-mcp) all calculate it
the same way, from the same data.

## Create a custom metric

<Steps>
  <Step title="Open the builder">
    On **Ads**, select **metrics**, then **New custom metric**. On **Reports**, open the
    **Metric** picker in the **New report** sheet and select **New custom metric**.
  </Step>

  <Step title="Pick a type">
    Select `Rate`, `Cost per`, `Ratio`, or `Formula`.
  </Step>

  <Step title="Pick the metrics">
    Fill in the fields for that type. The table below lists them.
  </Step>

  <Step title="Check the value">
    On **Ads**, **On screen** shows the value for the rows in the table now.
  </Step>

  <Step title="Name it">
    Type a name in **Name (optional)**, up to 60 characters. Leave it empty to keep the
    suggested name.
  </Step>

  <Step title="Save">
    Select **Add metric**. On **Ads**, the metric is added as a column.
  </Step>
</Steps>

| Type | Fields | Calculates | Shown as |
| - | - | - | - |
| `Rate` | **Count**, **Out of** | Count ÷ Out of | Percentage, for example `4.20%` |
| `Cost per` | **Cost per** | Spend ÷ the metric | Currency |
| `Ratio` | **Divide**, **By** | Divide ÷ By | Multiple, for example `2.50×` |
| `Formula` | Metrics, `+ − × ÷`, parentheses, numbers | Any formula with up to 10 metrics | `%`, `$`, `#`, or `×`, with 0 to 4 decimals |

A workspace holds up to 50 custom metrics. Every member can create, edit, and delete them.

## Metrics you can use

| Group | Metrics | Platforms |
| - | - | - |
| Delivery | Spend, Impressions, Clicks (all) | Meta, Google, TikTok |
| Delivery | Link clicks | Meta |
| Delivery | Video plays, 3-sec views (TikTok: 2-sec views) | Meta, TikTok |
| Platform-reported | Results, Conversion value | Meta, Google, TikTok |
| Platform-reported | Meta purchases, trial starts, app installs, leads, subscriptions, adds to cart, checkouts, payment info added, content views | Meta |
| DATALYR | Conversions, Revenue (USD) | Meta, Google, TikTok |
| DATALYR events | Any event you track, counted per ad | Meta, Google, TikTok |

A custom metric applies only to the platforms that report every metric in it. `Meta adds to
cart ÷ Link clicks` applies to Meta only: Google and TikTok rows show `–`, and the total
covers Meta rows only.

## How the value is calculated

* Each metric in the formula is summed first. The formula then runs once on the sums. A
  rate over three campaigns is total adds to cart ÷ total link clicks, not an average of
  three rates.
* An unknown value makes the result `–`, never `0`. A division by zero shows `–`.
* Spend and conversion value are in the ad account's currency. A total that adds accounts
  in different currencies shows `–`. A formula that uses DATALYR revenue and spend needs a
  USD ad account.
* A formula can use up to 8 DATALYR events. The Ads table counts at most 8 DATALYR events
  across all visible columns.

## Use it in Reports

In the **New report** sheet, pick the custom metric from the **Custom** group of the
**Metric** picker.

| Card | Shows |
| - | - |
| `Line`, `Area`, `Bar` | The value per day. Not available for formulas that use DATALYR metrics. |
| `Breakdown`, `Donut` | The value per **Ad platform** or per **Campaign** |
| Metric tile | One number for the range |

The card uses the same date range and accounts as **Ads**. Dashboard filters apply to a
custom-metric card only when they filter by platform.

## Use it in chat and agents

`list_custom_metrics` returns each custom metric with its ID, such as `cm:cm_ab12cd34ef`.
Pass the ID to `analytics_query` on its own, grouped by `platform` or `campaign`, or with
`granularity: "day"`. Agents with the `datalyr:write:reports` scope can create, update, and
delete custom metrics.

## Edit or delete

Open the picker and select the pencil next to the metric. A change applies everywhere the
metric is used. Select **Delete** to remove it. The toast offers **Undo**. A Reports card
that uses a deleted metric shows that the metric was deleted.

## Verify

Add the custom metric as a column on **Ads**. Compare its footer with a Reports metric tile
for the same metric and date range. The two numbers are the same.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.