Analytics

Analytics answers two questions from the events you already send: how many customers are active, and how many come back after their first day. There is nothing to set up. The dashboard shows it under Analytics, and the same numbers are available over the API with a key that has the analytics:read scope.

Active customers

A customer is active on a day when at least one of their events was accepted that day. GET /v1/analytics/activity?from=2026-09-01&to=2026-09-30 returns one row per day:

{
  "computed_at": "2026-10-01T09:00:12.000Z",
  "days": [
    {
      "day": "2026-09-30",
      "active_1d": 412,
      "active_7d": 1930,
      "active_30d": 5120,
      "new_customers": 38
    }
  ]
}

• active_1d: customers active that day.
• active_7d and active_30d: customers active at least once in the 7 or 30 days ending that day (rolling counts, each customer counted once).
• new_customers: customers whose first active day was that day.

Retention

Retention groups customers into cohorts by their first active day and asks, for each cohort, what share was active again exactly N days later, for N in 1, 3, 7, 14 and 30. This is classic day-N retention: a customer who was first active on 1 September counts toward day 7 only if they were active on 8 September.

GET /v1/analytics/retention?from=2026-09-01&to=2026-09-30&interval=day returns:

{
  "interval": "day",
  "computed_at": "2026-10-01T09:00:12.000Z",
  "cohorts": [
    {
      "cohort": "2026-09-01",
      "size": 40,
      "cells": [
        {
          "day_n": 1,
          "retained": 12,
          "rate": 0.3,
          "ci_low": 0.181,
          "ci_high": 0.454,
          "mature": true
        },
        { "day_n": 30, "retained": 0, "rate": 0, "ci_low": 0, "ci_high": 0, "mature": false }
      ]
    }
  ]
}

from and to select cohorts by their first day. interval=week adds daily cohorts up into weekly ones: cohort is then the first day of the week, and a customer still counts toward day N relative to their own first day.

Days are UTC

Cohort days and activity days are UTC calendar days, in every environment. An event at 23:30 in New York on 1 September belongs to 2 September. Per-environment time zones for analytics are not supported yet.

Maturity

A cell is mature once its day is over for the whole cohort. Until then mature is false and the dashboard shows a dash, because a rate computed halfway through the day would read too low. Do not treat an immature cell as zero.

Intervals

ci_low and ci_high are a 95% Wilson interval around rate: the range the true share is likely to be in, given the cohort's size. A cohort of 40 with a 30% rate has a wide interval (about 18% to 45%); a cohort of 4,000 has a narrow one. Compare two cohorts by their intervals, not only by their rates: when the intervals overlap heavily, the difference may be chance.

When the numbers are built

The numbers are not computed while you read them. A build runs every hour for every environment: it reads the events accepted since the last build, updates each customer's active days and first day, and recomputes the cohort cells and daily totals. Every response carries computed_at.

GET /v1/analytics/status reports when the last build finished and whether it failed.

To see results without waiting for the next hour, run the same build for one environment on demand (analytics:write):

curl -X POST https://api.orishare.com/v1/analytics/builds \
  -H "Authorization: Bearer $ORISHARE_SECRET_KEY"

The on-demand build has a time budget. In an environment with a large backlog it may stop early and report "complete": false; call it again to continue. The dashboard button "Refresh now" does exactly this.

Limits

• UTC only. See above.
• Events drive everything. A customer who never sends an event is in no cohort. A customer created through the API without any event is not "new" until their first event.
• Deleted customers leave the numbers. Deleting a customer removes their activity; the next build recomputes the cohorts without them.
• Merged customers. After a merge the surviving customer carries on from its own history; the merged-away customer's earlier active days are not moved onto it.
• No revenue or lifetime value here. This page is about activity and retention only.
• No breakdown by segment or attribute yet. Cohorts are per environment. To compare groups of customers, run an experiment.