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

# Create Metrics

> Learn how to create metrics using the API.

export const HowToSchema = ({name, description, steps = []}) => {
  const schema = {
    "@context": "https://schema.org",
    "@type": "HowTo",
    name,
    description
  };
  if (steps.length > 0) {
    schema.step = steps.map((s, i) => ({
      "@type": "HowToStep",
      position: i + 1,
      name: typeof s === "string" ? s : s.name,
      text: typeof s === "string" ? s : s.text || s.name
    }));
  }
  return <script type="application/ld+json" dangerouslySetInnerHTML={{
    __html: JSON.stringify(schema)
  }} />;
};

<HowToSchema
  name="Create Metrics"
  description="Learn how to create metrics using the API."
  steps={[
{
  name: "Before You Begin",
  text: "Before creating a metric, ensure you have: - An API access token with appropriate permissions - Created the entity you want to measure",
},
{
  name: "Create an Average Metric",
  text: "Create an average metric that measures the average sales amount per user:",
},
{
  name: "Create a Ratio Metric",
  text: "Create a ratio metric like conversion rate:",
},
{
  name: "Aggregation Types",
  text: "For average metrics, choose how to aggregate data within units: - AGGREGATION_TYPE_SUM: Sum all measurements - AGGREGATION_TYPE_COUNT: Count occurrences",
},
{
  name: "Time Windows",
  text: "The aggregationWindow defines how long after exposure to aggregate measurements: Common windows: - 86400s: 1 day",
},
{
  name: "Variance Reduction (CUPED)",
  text: "Enable or disable variance reduction to improve statistical power:",
},
]}
/>

Create metrics that aggregate measurements across instances of an entity.

## Before You Begin

Before creating a metric, ensure you have:

* An API access token with appropriate permissions
* Created the entity you want to measure
* Created a fact table with the measurements to aggregate
* Determined the aggregation type and time windows

## Create an Average Metric

Create an average metric that measures the average sales amount per user:

```bash theme={null}
curl -X POST "https://metrics.confidence.dev/v1/metrics" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Average sales amount per user during the first week after exposure",
    "entity": "entities/user",
    "factTable": "factTables/my-fact-table",
    "aggregationWindow": "604800s",
    "exposureOffset": "0s",
    "typeSpec": {
      "averageMetricSpec": {
        "measurement": {
          "name": "sales_amount",
          "repeated": false
        },
        "aggregation": {
          "type": "AGGREGATION_TYPE_SUM"
        }
      }
    },
    "varianceReductionConfig": {
      "disabled": false
    }
  }'
```

## Create a Ratio Metric

Create a ratio metric like conversion rate:

```bash theme={null}
curl -X POST "https://metrics.confidence.dev/v1/metrics" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Conversion rate in first week",
    "entity": "entities/user",
    "factTable": "factTables/conversions",
    "aggregationWindow": "604800s",
    "exposureOffset": "0s",
    "typeSpec": {
      "ratioMetricSpec": {
        "numerator": {
          "measurement": {
            "name": "converted",
            "repeated": false
          },
          "aggregation": {
            "type": "AGGREGATION_TYPE_SUM"
          }
        },
        "denominator": {
          "measurement": {
            "name": "eligible",
            "repeated": false
          },
          "aggregation": {
            "type": "AGGREGATION_TYPE_SUM"
          }
        }
      }
    },
    "varianceReductionConfig": {
      "disabled": false
    }
  }'
```

## Aggregation Types

For average metrics, choose how to aggregate data within units:

* `AGGREGATION_TYPE_SUM`: Sum all measurements
* `AGGREGATION_TYPE_COUNT`: Count occurrences
* `AGGREGATION_TYPE_COUNT_DISTINCT`: Count unique values
* `AGGREGATION_TYPE_MAX`: Maximum value
* `AGGREGATION_TYPE_MIN`: Minimum value
* `AGGREGATION_TYPE_UNIQUE`: Single unique value (fails if multiple values exist)

## Time Windows

### Aggregation Window

The `aggregationWindow` defines how long after exposure to aggregate measurements:

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

Common windows:

* `86400s`: 1 day
* `604800s`: 7 days
* `2592000s`: 30 days

### Exposure Offset

The `exposureOffset` defines how long to wait after exposure before starting measurement:

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

Example with delay:

```json theme={null}
"exposureOffset": "86400s"  // Wait 1 day before measuring
```

## Variance Reduction (CUPED)

Enable or disable variance reduction to improve statistical power:

### Enabled (Default)

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

### Disabled

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

## Next Steps

After creating metrics:

* Configure experiments to track these metrics
* Analyze experiment results using these metrics
* Create additional metrics to measure different aspects of user behavior