> ## 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](https://confidence.spotify.com/docs/reference/api/metrics/concepts.md#metrics) in the Metrics Concepts page.

## 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:

**Enabled (Default)**

```json theme={null}
{
  "varianceReductionConfig": {
    "disabled": false
  }
}
```

Recommended for most metrics. Requires pre-exposure data.

**Disabled**

```json theme={null}
{
  "varianceReductionConfig": {
    "disabled": true
  }
}
```

Use when:

* No pre-exposure data available
* Metric is new user only
* Testing CUPED impact

## Metric Resource Name Format

Reference metrics using the resource name format:

```text theme={null}
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