Custom Metrics

Send your product's own numbers, such as credits, seats or active campaigns, and chart them over time next to signups and revenue.

Ripples counts visitors, signups, activation and revenue on its own. Custom metrics add the numbers only your product knows: images generated, credits left, seats, campaigns running. They appear on Dashboards, on company and person pages, and through the ripples_metric MCP tool, in the same windows and filters as everything else.

Which path a number takes

The number is Send it as Example
Something a person did A track() event, with any quantity as a property generation_completed with credits: 3
A value the signed-in person's page already holds A trait on identify() or group() The credit balance shown in the header
State that lives on your server A snapshot from a scheduled job, or a warehouse source Active campaigns per company, seats, open invoices

Why state should not come from the browser

  • The page has to fetch the values first. Counts of campaigns or invoices are rarely on the page, so every load would need an API call, for modules the user may never open.
  • Values change with nobody watching. Cron jobs, admin edits and other services change state, and a browser that is closed sends nothing, so totals go stale and look stable.
  • A company’s numbers would come from one member’s browser, whichever member signed in last.
  • Blockers and closed tabs drop sends, and nothing tells Ripples a value was missed.

Events: quantities on the action

An event metric needs no setup. Any track() event can be counted, by events, people or companies, and any numeric property can be summed, averaged or maxed:

ripples.track("generation_completed", { credits: 3, model: "fast" })
  • Send numbers as JSON numbers (3, not "3").
  • A spent amount belongs on the event that spent it, not in a trait. A balance is a trait.
  • A sum needs a unit. Put it in the property’s name (cost_usd, litres), or send the unit as its own property (currency: "EUR") and the sum is split by it. Ripples never adds euros to dollars.
  • A counter that resets each period (“trips this month”) is an event metric: send one event per trip.

Traits: a value right now

A numeric trait on identify() is a value of a person; on group() it is a value of a company:

ripples.identify("user_42", { credits: 140 })
ripples.group("acme_7", { seats: 12, active_campaigns: 3 })

Track a trait to keep its history

Ripples keeps the history of a trait only once the trait is tracked. Tracking is a project setting, made through the Ripples MCP server (ripples_configure, action manage_traits): ask your assistant to “track the person trait credits as an amount in credits”. Every change is attributed to whoever made it. A project tracks up to 200 traits.

History starts the moment a trait is tracked: each owner’s current value is written then. Nothing earlier can be recovered from Ripples, so track a trait before you need its chart. Past values can still be loaded with $history_only.

Each tracked trait declares a kind, which fixes how its values may be combined:

Kind For Combined as
count Things owned: seats, vehicles, campaigns Sum, average, min, max, how many have any
amount A balance in one unit: credits, account balance The same, summed only within its unit, which is required
score A level: health score, readiness, accuracy Average, min, max, how many reach a threshold. Never summed
flag Yes or no: is_pro, onboarded How many, and what share, are true

Values

  • A JSON number, a numeric string ("3") or a boolean (true counts as 1) is stored. Anything else is ignored.
  • null clears the value. A deleted entity must be sent as null, or left out of a complete snapshot.
  • Ripples keeps at most one value per owner, trait and hour (the last), and writes only when the value changes, so sending the same value again costs nothing.
  • Ids, keys ending in _id, dates (_at, _date), email, name, plan and keys starting with $ or _rpl_ cannot be tracked.

Snapshots: state from your server

A snapshot sends many owners’ current values in one call, from a job you run nightly or hourly. It is the main path for server state: one job, every owner, and values that did not change cost nothing.

POST https://api.ripples.sh/v1/ingest/batch with your secret key:

curl -X POST https://api.ripples.sh/v1/ingest/batch \
  -H "Authorization: Bearer priv_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "$type": "snapshot",
      "owner_type": "company",
      "traits": ["active_campaigns", "seats"],
      "values": {
        "acme_7": { "active_campaigns": 12, "seats": 30 },
        "globex_2": { "active_campaigns": null }
      },
      "as_of": "2026-11-18T03:30:00Z",
      "snapshot_id": "nightly-2026-11-18",
      "complete": true,
      "expected": { "active_campaigns": 12 }
    }]
  }'
Field Type Description
owner_type required string person (keyed by your user id) or company (keyed by the company id you send to group()).
traits required array 1 to 50 keys, each already tracked.
values required object Owner key to {trait: value}. Up to 1,000 owners per event and 5,000 per request. A trait an owner leaves out keeps its value; null clears it.
as_of optional string ISO 8601 time the values were true. Defaults to now; never later than now.
snapshot_id optional string Names one run. Required with complete or expected; every chunk of the run carries it, and the chunks must arrive within 24 hours.
complete optional boolean On the last chunk only: clears every owner holding a value who was not sent in this run. See below.
expected optional object Your own total per trait. If Ripples' total differs by more than 0.5%, the project's health shows snapshot_mismatch for 7 days.
$history_only optional boolean Write history only and leave current values alone. For backfills.

Only owners Ripples already knows are updated: people who have been identified with that user id, and companies sent through group(). Others are skipped and counted, so a snapshot never creates people. Send identify() and group() as usual for new users and companies.

The response

{
  "ok": true,
  "snapshots": [
    { "snapshot_id": "nightly-2026-11-18", "owners": 2, "written": 2, "unchanged": 0, "skipped_unknown": 0, "complete": "queued" }
  ]
}

A refused chunk does not fail the request. It comes back under rejected with a reason, and nothing in it was applied, so fix it and send it again:

Reason Meaning
not_secret_keySnapshots need the secret key.
trait_not_trackedA listed trait is not tracked yet.
trait_owned_by_sourceA listed trait is written by a warehouse source only.
too_many_ownersMore than 1,000 owners in one event, or 5,000 in one request.
bad_snapshotA malformed field; the reason says which.
snapshot_failedRipples could not apply it. Send it again.

Complete snapshots and deletes

When an entity is deleted on your side, its last value would otherwise stay in Ripples and keep counting. complete: true on the last chunk of a run clears every owner who holds a value and was not sent in that run. A complete snapshot covers up to 250,000 owners. A clear that would remove more than 20% of the owners holding a value (and more than 50) is refused and shown in the project’s health, because that is usually a lost chunk rather than real deletes.

A nightly job, in chunks

Python:

import requests

def send_snapshot(companies, snapshot_id, as_of, secret_key):
    """companies: {company_id: {"active_campaigns": 12, "seats": 30}}"""
    owners = list(companies.items())
    chunks = [owners[i:i + 1000] for i in range(0, len(owners), 1000)]
    for n, chunk in enumerate(chunks):
        event = {
            "$type": "snapshot",
            "owner_type": "company",
            "traits": ["active_campaigns", "seats"],
            "values": dict(chunk),
            "as_of": as_of,
            "snapshot_id": snapshot_id,
        }
        if n == len(chunks) - 1:
            event["complete"] = True
        r = requests.post(
            "https://api.ripples.sh/v1/ingest/batch",
            headers={"Authorization": f"Bearer {secret_key}"},
            json={"events": [event]},
            timeout=60,
        )
        r.raise_for_status()
        if r.json().get("rejected"):
            raise RuntimeError(r.json()["rejected"])

PHP:

function sendSnapshot(array $companies, string $snapshotId, string $asOf, string $secretKey): void
{
    $chunks = array_chunk($companies, 1000, true);

    foreach ($chunks as $n => $chunk) {
        $event = [
            '$type' => 'snapshot',
            'owner_type' => 'company',
            'traits' => ['active_campaigns', 'seats'],
            'values' => $chunk,
            'as_of' => $asOf,
            'snapshot_id' => $snapshotId,
        ];
        if ($n === array_key_last($chunks)) {
            $event['complete'] = true;
        }

        $ch = curl_init('https://api.ripples.sh/v1/ingest/batch');
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => ["Authorization: Bearer {$secretKey}", 'Content-Type: application/json'],
            CURLOPT_POSTFIELDS => json_encode(['events' => [$event]]),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 60,
        ]);
        $body = json_decode((string) curl_exec($ch), true);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);

        if ($status !== 200 || ! empty($body['rejected'])) {
            throw new RuntimeException('Snapshot chunk failed: '.json_encode($body));
        }
    }
}

Send the chunks one after another, not in parallel, so complete arrives last.

Backfills and repairs: $history_only

$history_only: true writes history rows for the tracked keys of the call, dated by $sent_at, and changes nothing else: no profile, no company, no signup. Use it to load the past from your own records, or to correct a period that was sent wrong.

{
  "events": [
    { "$type": "identify", "$user_id": "42", "$sent_at": "2026-10-01T00:00:00Z", "$history_only": true, "credits": 500 },
    { "$type": "group", "$company_id": "acme_7", "$sent_at": "2026-10-01T00:00:00Z", "$history_only": true, "$traits": { "seats": 25 } }
  ]
}

From the SDKs, pass it with the values and date the call:

$ripples->identify('42', ['credits' => 500, '$history_only' => true], new DateTimeImmutable('2026-10-01'));
ripples.identify("42", timestamp="2026-10-01T00:00:00Z", credits=500, **{"$history_only": True})

A snapshot takes "$history_only": true too, for a whole day of owners in one call. Load the past oldest first, one call per date.

Warehouse sources

If your product’s state is already in BigQuery, Ripples can run a saved read-only query on a schedule and write what it returns, with no code in your app. The query defines the numbers once, including which accounts are staff or tests, and history can often be rebuilt from your own timestamps. Sources are set up through the MCP server (ripples_configure, action manage_metric_sources) once the project has a BigQuery connection; every save needs a preview of that exact query.

Keeping the numbers right

  • Send full state on a schedule, not only on change. A value sent once and changed later by an admin edit or a cron job is wrong until the next send. A nightly full snapshot heals it within a day, and unchanged values cost nothing.
  • Send deletes. null, or a complete snapshot.
  • Count the way you send. If your own totals leave out test accounts, leave them out of the snapshot too, and send expected to catch any difference.
  • Ripples watches the senders. When a tracked trait that reports regularly has had no report for longer than twice its usual gap (and at least 24 hours), the project’s health shows trait_sender_quiet, every read of that trait carries it, and dashboard blocks that show it get a mark. The same goes for a failing or stuck warehouse source and a snapshot that disagrees with your totals.
  • A value that is wrong at your source is out of Ripples’ reach. Compare a few totals with your own admin now and then.