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

# Custom metrics

> User-defined calculations built from base metrics or other custom metrics.

A **custom metric** is a calculation defined by the user, built from base metrics, other custom metrics, or numeric constants. Use custom metrics for calculations that aren't provided by any single data source — for example, a blended CPA across multiple ad platforms, gross margin from spend and revenue, or a target-adjusted efficiency ratio.

Once created, a custom metric appears in the metric picker on every applicable widget alongside the base metrics.

## When to use a custom metric

* **Blended metrics** — combine metrics from multiple ad platforms into one calculation.
* **Business-specific ratios** — margins, ROI, or LTV-to-CAC that no single data source provides natively.
* **Reused calculations** — a formula used on many widgets is easier to define once.

## Create a custom metric

Custom metrics are created from a widget's settings panel:

<Steps>
  <Step title="Open the widget's settings panel">
    Pick any widget on the dashboard, and open its settings panel.
  </Step>

  <Step title="Open the metric panel">
    Open the metric picker inside the settings panel and click the **+ Custom metric** button at the top.
  </Step>

  <Step title="Build the formula">
    In the custom metric editor, pick base metrics from the metric picker and combine them using math operators (`+`, `-`, `*`, `/`, parentheses). Base metrics from every connected data source are available.
  </Step>

  <Step title="Set the type and precision">
    Pick the metric **type** and **precision**:

    * **Type** — one of **Number**, **Percentage**, **Currency**, or **Duration**.
    * **Precision** — the number of decimal places, from **0** to **4**.
  </Step>

  <Step title="Name and save">
    Give the custom metric a name and save. It becomes available in the metric picker on every widget that supports custom metrics.
  </Step>
</Steps>

## Edit or delete a custom metric

From the same metric panel where the custom metric was created, hover over an existing custom metric to reveal edit and delete actions.

Deleting a custom metric that's referenced by dashboard widgets triggers a warning — widgets currently using it will render the value as `-` once deleted.

## Formula basics

Custom metrics use base metrics, constants, and standard math operators. Examples:

* **Blended CPA** — `(Meta Spend + Google Spend) / (Meta Conversions + Google Conversions)`.
* **Gross margin** — `(Revenue - Spend) / Revenue`.
* **Cost per session** — `Ad Spend / GA4 Sessions`.

## Null handling

The formula evaluates row by row. Two rules apply when values are missing:

* **All referenced metrics are null on a row** — the row's custom metric value is also null (renders as `-`). The row genuinely has no data.
* **Some referenced metrics are null** — nulls are treated as `0` before the formula runs, and the formula evaluates. The result is a real number, or `-` if the formula produces division-by-zero or an invalid result.

## Conditional formulas

A custom metric can carry **multiple formulas** — each with its own condition. Adriel evaluates conditions top to bottom and uses the first formula whose condition matches the row.

Common use cases:

* Apply one formula for one channel and a different formula for another.
* Use a fallback formula for rows that don't match any specific condition.

The formula editor requires an **else** fallback — the formula that runs when no other condition matches. In the UI, this fallback lives in the **Then** section at the bottom of the formula list. Every custom metric with conditional formulas needs a value in the Then section so a fallback is guaranteed. The first matching condition wins; later matching conditions are ignored.

## Scope

Custom metrics can be created at three scopes:

* **Workspace-scoped** — available across every teamspace and dashboard.
* **Teamspace-scoped** — available only in the teamspace where it was created.
* **Dashboard-scoped** — available only on the dashboard where it was created.

Dashboard-scoped custom metrics can override a workspace-level metric with the same name — useful for a one-off dashboard that needs a slightly different calculation without affecting every other dashboard.

## Referencing custom metrics in other custom metrics

A custom metric can reference another custom metric. Chains resolve in dependency order:

* **Cycles are forbidden** — a custom metric can't reference itself directly or transitively.
* **Missing references** — a custom metric that references a base metric no longer present in the workspace evaluates to `null` for every row.

## Troubleshooting

For common problems — formula scoping, deleted-metric behavior, cache refresh, decimal precision on tooltips, and why the total row doesn't equal the sum of the breakdown rows — see the [Breakdowns & metrics FAQs](/widgets/breakdowns-and-metrics/faqs).

## Related

<CardGroup cols={2}>
  <Card title="Metrics" href="/widgets/breakdowns-and-metrics/metrics">
    The base metrics custom calculations build on.
  </Card>

  <Card title="Custom breakdowns" href="/widgets/breakdowns-and-metrics/custom-breakdowns">
    The breakdown-side counterpart.
  </Card>

  <Card title="Multi-currency reporting" href="/dashboards/building/multi-currency-reporting">
    How currency conversion interacts with currency-typed metrics.
  </Card>
</CardGroup>