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

# Metrics Reference

> Technical reference for metrics in Confidence Metrics.

This section provides technical specifications and reference information for metrics.

<Tip>
  For conceptual explanations of metrics, see [Metrics](./concepts#metrics) in the Metrics Concepts page.
</Tip>

## Metric Types

### Average Metrics

Aggregate a single measurement across entities:

```json theme={null}
{
  "typeSpec": {
    "averageMetricSpec": {
      "measurement": {
        "name": "purchase_amount",
        "repeated": false
      },
      "aggregation": {
        "type": "AGGREGATION_TYPE_SUM"
      }
    }
  }
}
```

### Ratio Metrics

Compute a ratio of two aggregated measurements:

```json theme={null}
{
  "typeSpec": {
    "ratioMetricSpec": {
      "numerator": {
        "measurement": {
          "name": "converted",
          "repeated": false
        },
        "aggregation": {
          "type": "AGGREGATION_TYPE_SUM"
        }
      },
      "denominator": {
        "measurement": {
          "name": "eligible",
          "repeated": false
        },
        "aggregation": {
          "type": "AGGREGATION_TYPE_SUM"
        }
      }
    }
  }
}
```

## Aggregation Types

| Type                              | Description                             | Use Case                                 |
| :-------------------------------- | :-------------------------------------- | :--------------------------------------- |
| `AGGREGATION_TYPE_SUM`            | Sum all values                          | Total revenue, total conversions         |
| `AGGREGATION_TYPE_COUNT`          | Count all occurrences                   | Number of events, session count          |
| `AGGREGATION_TYPE_COUNT_DISTINCT` | Count unique values                     | Unique items viewed, distinct categories |
| `AGGREGATION_TYPE_MAX`            | Maximum value                           | Highest price, longest session           |
| `AGGREGATION_TYPE_MIN`            | Minimum value                           | Lowest price, shortest session           |
| `AGGREGATION_TYPE_UNIQUE`         | Single unique value (fails if multiple) | Latest status, final state               |

## Time Windows

### Aggregation Window

Duration after exposure to aggregate measurements:

```json theme={null}
"aggregationWindow": "604800s"  // 7 days in seconds
```

Common windows:

* `86400s`: 1 day
* `604800s`: 7 days (1 week)
* `1209600s`: 14 days (2 weeks)
* `2592000s`: 30 days (\~1 month)

### Exposure Offset

Delay before starting measurement:

```json theme={null}
"exposureOffset": "0s"  // Start immediately
```

Use cases:

* `0s`: Immediate effect (UI changes, performance)
* `86400s`: 1-day delay (email campaigns)
* `604800s`: 1-week delay (long-term behavior)

## Variance Reduction (CUPED)

Variance reduction improves statistical power by reducing noise in metric estimates:

<Tabs>
  <Tab title="Enabled (Default)">
    ```json theme={null}
    {
      "varianceReductionConfig": {
        "disabled": false
      }
    }
    ```

    Recommended for most metrics. Requires pre-exposure data.
  </Tab>

  <Tab title="Disabled">
    ```json theme={null}
    {
      "varianceReductionConfig": {
        "disabled": true
      }
    }
    ```

    Use when:

    * No pre-exposure data available
    * Metric is new user only
    * Testing CUPED impact
  </Tab>
</Tabs>

## Metric Resource Name Format

Reference metrics using the resource name format:

```
metrics/{metric_id}
```

Example: `metrics/conversion-rate`, `metrics/average-revenue`

## Required Fields

| Field               | Type   | Description                                         |
| :------------------ | :----- | :-------------------------------------------------- |
| `displayName`       | string | Human-readable metric name                          |
| `entity`            | string | Entity resource name (for example, `entities/user`) |
| `factTable`         | string | Fact table resource name                            |
| `aggregationWindow` | string | Duration in seconds (ISO 8601)                      |
| `exposureOffset`    | string | Duration in seconds (ISO 8601)                      |
| `typeSpec`          | object | Average or ratio metric specification               |

## Best Practices

### Choose Metric Types

* **Average metrics**: Use for continuous values (revenue, duration, ratings)
* **Ratio metrics**: Use for rates and percentages (conversion rate, CTR, success rate)

### Aggregation Selection

* **SUM**: Default for most measurements (revenue, clicks, conversions)
* **COUNT**: When you only care about occurrence, not value
* **COUNT\_DISTINCT**: When each unique value matters (unique products, categories)
* **MAX/MIN**: When extremes are important (peak load, worst performance)

### Time Window Considerations

* **Shorter windows** (1-7 days): Faster results, earlier decisions
* **Longer windows** (14-30 days): Capture long-term effects, slower to significance
* **Match business cycle**: Align with purchase cycles, subscription periods

### Variance Reduction

* Enable CUPED for most metrics to improve sensitivity
* Disable for new user metrics or when no historical data exists
* Monitor CUPED effectiveness in analysis results