Custom metrics

A custom metric is a saved lens over the events you already track. It does not add new tracking. It tells Versuch how to roll a tracked event up into a number: which event to read, how to aggregate it, which direction is good, and how to format it.

Because metrics are computed at analysis time, defining one is retroactive: it applies to events already in the store, not just events sent after you create it.

The definition shape

Metric definition

{
  "name": "Checkout revenue",
  "key": "checkout_revenue",
  "description": "Revenue per exposed visitor from checkout events",
  "event": "checkout",
  "aggregation": "sum",
  "direction": "higher",
  "format": "usd"
}

Field	What it does
name	Human label shown in the dashboard and results. Required.
key	Stable id used by the API. Auto-generated from name if omitted.
description	Optional note describing what the metric measures.
event	The tracked event name this metric aggregates (for example checkout, signup). Required.
aggregation	sum, mean, count, or conversion.
direction	higher or lower: which way is a win.
format	usd, percent, seconds, or number: how the value renders.

Aggregation types

• conversion: the share of exposed visitors who fired the event at least once. Use for signup rate, purchase rate, activation.
• count: how many times the event fired per visitor. Use for events per session, actions taken.
• sum: the total of the event’s value across a visitor. Use for revenue, total items.
• mean: the average value per event. Use for average order value, average time.

sum and mean read the event’s value field, so make sure you send a value when you track those events. Values are in minor units (cents), and usd formatting divides accordingly.

Direction

direction tells the stats engine which way counts as an improvement. For revenue and signups that is higher. For refunds, latency, or churn that is lower. Results read the significance against control in the correct direction, so a metric where lower is better does not get flagged as a loss for going down.

Create a metric

REST API

POST https://versuch.ai/api/v1/metrics with a secret key.

Define a custom metric

curl -X POST https://versuch.ai/api/v1/metrics \
  -H "Authorization: Bearer vsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout revenue",
    "description": "Revenue per exposed visitor from checkout events",
    "event": "checkout",
    "aggregation": "sum",
    "direction": "higher",
    "format": "usd"
  }'

List and delete:

List and delete

# List all metric definitions
curl https://versuch.ai/api/v1/metrics \
  -H "Authorization: Bearer vsk_live_…"

# Delete a metric (also detaches it from any experiments)
curl -X DELETE https://versuch.ai/api/v1/metrics/checkout_revenue \
  -H "Authorization: Bearer vsk_live_…"

Deleting a metric detaches it from every experiment it was attached to. The underlying events are untouched.

Dashboard

1. Open your project and go to Metrics, then New metric.

2. Enter a name and pick the event it aggregates.

3. Choose the aggregation (conversion, count, sum, or mean), the direction, and the display format.

4. Save. The metric is immediately available to attach to experiments.

📸 Visual

Placeholder, the New metric form with the event picker, aggregation dropdown, direction toggle, and format selector filled in. Source: dashboard (auth).

Attach a metric to an experiment

A metric only affects results once it is attached to an experiment. Attach a primary metric and optional guardrails:

Attach metrics to an experiment

curl -X PUT https://versuch.ai/api/v1/experiments/exp_123/metrics \
  -H "Authorization: Bearer vsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "primary": "checkout_revenue",
    "guardrails": ["signup_rate", "refund_rate"]
  }'

• primary: the metric the experiment is decided on.
• guardrails: metrics you want to watch for regressions while the primary moves. A guardrail with direction: "lower" (like refund_rate) flags if it goes up.

Once attached, results show direction-aware significance per metric: the primary drives the call, and each guardrail is reported alongside so you can see the trade-offs.

Tip

Define the events you care about once with stable names in tracking, then build metrics on top of them. You can add and swap metrics on a running experiment without changing any tracking code.