List available measures

GET

/v1/metrics/measures

curl "https://api.summerbase.com/v1/metrics/measures" \
  -H "Authorization: Bearer sb_..."

Every measure POST /v1/metrics can answer with, in the order a table shows them: its key, what to call it, its unit, what it can be broken down by, and the window it is read over. Ask for any number of them by key, in measure. Every measure comes back on the first page.

All measures

Every measure there is, by what it is about: its name, its key, which is what measure takes and what an answer carries its values under, what it is and its unit. An amount is in the reporting currency, and a percentage is already scaled, so 4.2 is 4.2%. Each value is read over its period, unless the measure says it is read over a rolling interval — one interval back from each period’s end — or a year: the window it is read over when it comes first in measure and the query names none.

Run rate

MRR and ARR as they opened, moved and closed, and how many customers moved them.

Measure	What it is
Starting MRR starting_mrr	mrr as it stood at the start of each window. Unit: money
New MRR new_mrr	The MRR added in each window by customers who started paying for the first time, whether or not they still pay at its end. Unit: money
Expansion MRR expansion_mrr	The MRR added in each window by paying customers who came to pay more. Unit: money
Reactivation MRR reactivation_mrr	The MRR added in each window by customers who started paying again after having churned. Unit: money
Churned MRR churned_mrr	The MRR lost in each window to customers who stopped paying, as a positive amount, including those who started inside it. starting_mrr_lost counts only those paying at its start. Unit: money
Contraction MRR contraction_mrr	The MRR lost in each window to customers who came to pay less and still pay something, as a positive amount. Unit: money
Exchange Rate MRR exchange_rate_mrr	How much mrr changed in each window because exchange rates moved, with nobody paying differently in their own currency: positive when the currencies customers pay in strengthened against the reporting currency, and zero for a project whose customers all pay in it. Unit: money
MRR Movement mrr_movement	How much mrr changed over each window: what was new, expanded and reactivated, minus what contracted and churned, plus what exchange rates moved it by. Formula: new_mrr plus expansion_mrr plus reactivation_mrr minus contraction_mrr minus churned_mrr plus exchange_rate_mrr, and under a filter or a breakdown, what entered the category less what left it. Unit: money
Run Rate Movers run_rate_movers	The number of customers whose revenue changed over each window. Unit: count
MRR mrr	The Monthly Run Rate: revenue per month from every active subscription at the end of each window, after discounts, recurring and usage alike. Unit: money
MRR Growth mrr_growth	How much mrr grew or fell over each window, as a percentage. Formula: mrr_movement divided by starting_mrr. Read over a rolling interval unless the query says otherwise. Unit: percent
Starting ARR starting_arr	arr as it stood at the start of each window. Unit: money
New ARR new_arr	The ARR added in each window by customers who started paying for the first time, whether or not they still pay at its end. Unit: money
Expansion ARR expansion_arr	The ARR added in each window by paying customers who came to pay more. Unit: money
Reactivation ARR reactivation_arr	The ARR added in each window by customers who started paying again after having churned. Unit: money
Churned ARR churned_arr	The ARR lost in each window to customers who stopped paying, as a positive amount, including those who started inside it. starting_arr_lost counts only those paying at its start. Unit: money
Contraction ARR contraction_arr	The ARR lost in each window to customers who came to pay less and still pay something, as a positive amount. Unit: money
Exchange Rate ARR exchange_rate_arr	How much arr changed in each window because exchange rates moved, with nobody paying differently in their own currency: positive when the currencies customers pay in strengthened against the reporting currency, and zero for a project whose customers all pay in it. Unit: money
ARR Movement arr_movement	How much arr changed over each window: what was new, expanded and reactivated, minus what contracted and churned, plus what exchange rates moved it by. Formula: new_arr plus expansion_arr plus reactivation_arr minus contraction_arr minus churned_arr plus exchange_rate_arr, and under a filter or a breakdown, what entered the category less what left it. Unit: money
ARR arr	The Annual Run Rate: revenue per year from every active subscription at the end of each window, after discounts, recurring and usage alike. Unit: money
ARR Growth arr_growth	How much arr grew or fell over each window, as a percentage. Formula: arr_movement divided by starting_arr. Read over a rolling interval unless the query says otherwise. Unit: percent

Run rate of the starting customers

What the customers paying at the window’s start lost, gained and kept of their MRR and ARR.

Measure	What it is
Starting MRR Lost starting_mrr_lost	How much less per month the customers paying at the start of each window pay at its end: churn and contraction. Unit: money
Starting MRR Gained starting_mrr_gained	How much more per month the customers paying at the start of each window pay at its end: expansion. Unit: money
Starting MRR Retained starting_mrr_retained	What the customers paying at the start of each window pay per month at its end, expansion included, so it exceeds starting_mrr when they grew. Unit: money
Starting ARR Lost starting_arr_lost	How much less per year the customers paying at the start of each window pay at its end: churn and contraction. Unit: money
Starting ARR Gained starting_arr_gained	How much more per year the customers paying at the start of each window pay at its end: expansion. Unit: money
Starting ARR Retained starting_arr_retained	What the customers paying at the start of each window pay per year at its end, expansion included, so it exceeds starting_arr when they grew. Unit: money

Customers

Customers and paying customers as they opened, moved and closed, and who started and stopped paying.

Measure	What it is
Starting Customers starting_customers	customers as it stood at the start of each window. Unit: count
Net New Customers net_new_customers	How much customers changed over each window. Unit: count
Customers customers	Every customer known at the end of each window, whatever their status: leads, free, trialing, paying and churned. Unit: count
Starting Paying Customers starting_paying_customers	paying_customers as it stood at the start of each window. Unit: count
New Paying Customers new_paying_customers	The number of customers who started paying for the first time in each window, whether or not they still pay at its end. Unit: count
Reactivated Paying Customers reactivated_paying_customers	How many times customers started paying again in each window after having churned, whether or not they still pay at its end; a customer who came back twice counts twice. Unit: count
Churned Paying Customers churned_paying_customers	How many times customers stopped paying in each window, including those who started inside it; a customer who churned twice counts twice. starting_paying_customers_lost counts only those paying at its start. Unit: count
Net New Paying Customers net_new_paying_customers	How much paying_customers changed over each window, except that under a breakdown or a filter a customer who moved category is neither. Formula: new_paying_customers plus reactivated_paying_customers minus churned_paying_customers. Unit: count
Paying Customers paying_customers	The number of customers with revenue at the end of each window. Unit: count

Starting customers

How many of the customers paying at the window’s start were lost and kept.

Measure	What it is
Starting Paying Customers Lost starting_paying_customers_lost	The number of customers with revenue at the start of each window who have none at its end. Unit: count
Starting Paying Customers Retained starting_paying_customers_retained	The number of customers with revenue at both the start and the end of each window. Unit: count

Churn and retention

The share of the customers paying at the window’s start, and of their revenue, lost and kept.

Measure	What it is
Gross Revenue Churn gross_revenue_churn	The share of revenue lost to churn and contraction over each window. Formula: starting_mrr_lost divided by starting_mrr, taken at the exchange rate of each window’s end rather than its start, as starting_mrr_lost is. Read over a rolling interval unless the query says otherwise. Unit: percent
Net Revenue Churn net_revenue_churn	The share of revenue lost over each window after expansion is counted; negative when existing customers grew. Formula: starting_mrr_lost minus starting_mrr_gained, divided by starting_mrr, taken at the exchange rate of each window’s end rather than its start, as the other two are. Read over a rolling interval unless the query says otherwise. Unit: percent
Gross Revenue Retention gross_revenue_retention	The share of revenue kept over each window, before any expansion. Formula: starting_mrr minus starting_mrr_lost, divided by starting_mrr, with starting_mrr taken at the exchange rate of each window’s end rather than its start, as starting_mrr_lost is. Read over a year unless the query says otherwise. Unit: percent
Net Revenue Retention net_revenue_retention	The share of revenue kept over each window, expansion included; above 100% when existing customers grew. Formula: starting_mrr_retained divided by starting_mrr, taken at the exchange rate of each window’s end rather than its start, as starting_mrr_retained is. Read over a year unless the query says otherwise. Unit: percent
Customer Churn customer_churn	The share of paying customers lost over each window. Formula: starting_paying_customers_lost divided by starting_paying_customers. Read over a rolling interval unless the query says otherwise. Unit: percent
Monthly Customer Churn monthly_customer_churn	customer_churn restated as a rate per month, whatever the length of each window. Read over a rolling interval unless the query says otherwise. Unit: percent
Customer Retention customer_retention	The share of paying customers kept over each window. Formula: starting_paying_customers_retained divided by starting_paying_customers. Read over a year unless the query says otherwise. Unit: percent

Revenue per account

What a paying customer pays on average.

Measure	What it is
ARPA per Month arpa_per_month	The Average Revenue Per Account per month: what a paying customer pays on average at the end of each window. Formula: mrr divided by paying_customers. Unit: money
ARPA per Year arpa_per_year	The Average Revenue Per Account per year: what a paying customer pays on average at the end of each window. Formula: arr divided by paying_customers. Unit: money

Funnel

Who is new at each step from lead to paying, the share of a step that reached a later one, and how long it took.

Measure	What it is
New Leads new_leads	The number of customers first seen in each window as leads. Unit: count
New Signups new_signups	The number of customers who signed up in each window. Unit: count
Signups Converted to Paid signups_converted_to_paid	The number of each window’s new_signups who have become paying since. A recent window reads low and rises as its signups convert. Unit: count
Signup-to-Paid Conversion signup_to_paid_conversion	The share of each window’s new_signups who have become paying since. A recent window reads low and rises as its signups convert. Formula: signups_converted_to_paid divided by new_signups. Read over a rolling interval unless the query says otherwise. Unit: percent
Leads Converted to Paid leads_converted_to_paid	The number of each window’s new_leads who have become paying since. A recent window reads low and rises as its leads convert. Unit: count
Lead-to-Paid Conversion lead_to_paid_conversion	The share of each window’s new_leads who have become paying since. A recent window reads low and rises as its leads convert. Formula: leads_converted_to_paid divided by new_leads. Read over a rolling interval unless the query says otherwise. Unit: percent
Median Lead-to-Paid Time median_lead_to_paid_time	The median number of days from first being seen as a lead to first paying, of the customers who became paying in each window. Read over a rolling interval unless the query says otherwise. Unit: days
Median Signup-to-Paid Time median_signup_to_paid_time	The median number of days from signing up to first paying, of the customers who became paying in each window. Read over a rolling interval unless the query says otherwise. Unit: days

Lifetime

How long a paying customer stays, and what they are worth over it.

Measure	What it is
Customer Lifespan customer_lifespan	How many months a paying customer stays on average, at each window’s rate of churn. Formula: one divided by monthly_customer_churn. Read over a rolling interval unless the query says otherwise. Unit: months
LTV ltv	The Lifetime Value: what a paying customer pays over the time they stay, before any cost. Formula: arpa_per_month times customer_lifespan. Read over a rolling interval unless the query says otherwise. Unit: money

Parameters

Query Parameters

limit

integer

default: 100 >= 1 <= 100

How many records to return, 1 to 100. Defaults to 100.

cursor

string

The next_cursor of the previous page, to read the page after it.

include_total_count

boolean

Whether to add total_count, how many records match altogether. On the first page only: it is the same number on every page of one list, so keep the first page’s, and it is refused beside a cursor.

Response

Returns a list of every measure a metrics query can ask for.

Media typeapplication/json

A page of results.

object

data

required

Array<object>

A measure is a kind of number a metrics query can ask for, such as mrr or customer_churn: what it is called, its unit, how it is read, and what it can be broken down by.

object

default_lookback_window

required

The window it is read over unless a query says otherwise, as lookback_window takes it: period for a level or a flow, rolling_interval for a rate, and 1y for a retention rate, which is quoted over a year. POST /v1/metrics reads every measure over the first one’s unless the query says otherwise.

string

description

required

What the number is, in a sentence or two, and its formula where it has one. It opens with its own key and names every other measure by its key in backticks: “mrr_growth is how much mrr grew or fell over each window, as a percentage. Formula: mrr_movement divided by starting_mrr.” Put each measure’s label in place of its key to show it to a person.

string

dimensions

required

What it can be broken down by: customer.* for any key about the customer, subscription.* and subscription_item.* likewise, and the revenue movements’ own — movement_type, revenue_type.

Array<string>

drill_through_unit

Whether POST /v1/metrics/drill_through/customers lists the customers behind a value of it, and what each one’s contribution there is in: money, their share of an amount; days, what they took; or count, where each customer is one and contribution is null. Null for a measure with nobody to list. A rate lists whoever is behind what it is over.

string

Allowed values: money days count

family

required

What it is about, for listing measures under headings: run_rate, run_rate_cohort, customers, customer_cohort, churn_and_retention or revenue_per_account.

string

Allowed values: run_rate run_rate_cohort customers customer_cohort churn_and_retention revenue_per_account funnel lifetime

good_direction

Which way it moving is good news: up for revenue and retention, down for churn and what was lost. Absent for a measure that says nothing either way — a starting value, or how many customers moved.

string

Allowed values: up down

id

required

The key it comes under in an answer, and the name measure takes.

string

label

required

What to call it: Revenue, Customer churn.

string

measure_type

required

What sort of value it has, which says how to draw it and what may be summed: level, a value at an instant — categories add up to it, periods do not; flow, what happened inside the window — categories and periods both add up; or rate, one value over another, a percentage or an amount per account — nothing adds up to it, so its categories are never stacked or totaled.

string

Allowed values: level flow rate

object

required

The object’s type, always measure.

string

Allowed values: measure

unit

required

money, an amount in the answer’s currency_code; count, a whole number; or percent, already scaled so that 4.2 is 4.2%.

string

Allowed values: money count percent days months

window_reading

required

What at: window means for this measure — when a breakdown’s or a filter’s value is read unless the query names an instant: end, the value in force at the end of each window, as a level is read; start, the value at the start of each window, where the cohort is, as churn and retention are read; or movement, the value in force when the money moved, as a flow is read. A rate reads as the more specific of its two sides.

string

Allowed values: end start movement

has_more

required

Whether another page follows this one.

boolean

next_cursor

Pass back as cursor to fetch the next page. Null on the last page.

string

object

required

string

Allowed values: list

total_count

How many records match altogether, counting every page. Only present when include_total_count=true was sent, on the first page.

integer

Example

{
  "data": [
    {
      "default_lookback_window": "period",
      "description": "`mrr` is the Monthly Run Rate: revenue per month from every active subscription at the end of each window, after discounts, recurring and usage alike.",
      "dimensions": [
        "customer.*",
        "subscription.*",
        "subscription_item.*",
        "movement_type",
        "revenue_type"
      ],
      "drill_through_unit": "money",
      "family": "run_rate",
      "good_direction": "up",
      "id": "mrr",
      "label": "MRR",
      "measure_type": "level",
      "object": "measure",
      "unit": "money",
      "window_reading": "end"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "object": "list",
  "total_count": 1
}