Skip to content

Reading Stats ​

Learn how to read revenue, subscriber, and attribution figures through the Management API.

Overview ​

The stats endpoints return the figures behind the dashboards in the Sesamy portal, as JSON you can chart or feed into your own reporting:

  • Metrics over time: GET /management/stats/series/{metric} returns one metric across a date range, as a headline figure and, for most metrics, a daily series per product. For example monthly recurring revenue or the number of subscribers.
  • Attribution breakdowns: GET /management/stats/breakdown/{dimension} groups purchases by where the visit came from, such as a UTM tag, the referrer, or the article.
  • The catalogue: GET /management/stats/catalogue lists every metric and dimension the other two endpoints accept.

To export raw rows, such as every transaction in a month, use Reports instead.

Base URL ​

https://api2.sesamy.com

Authentication ​

Every endpoint needs a Management API token with the stats:views:read scope. Both API key presets include it. Request the token from https://token.sesamy.com/oauth/token with the client credentials flow, and send it as a bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authentication for how to obtain a token.

Metrics ​

MetricUnitDescription
currentMrrcurrencyMonthly recurring revenue as of each day, per product
newMrrcurrencyRecurring revenue added by new subscriptions on each day
churnMrrcurrencyRecurring revenue lost to cancellations on each day
projectedMrrcurrencyProjected monthly recurring revenue for each day
totalRevenuecurrencyAll revenue recognised in the range, recurring and one-off
totalSalescurrencyTotal value of sales in the range. Headline figure only, with no series
subscriptionSalescurrencySales value from subscriptions on each day
totalSubscriberscountSubscribers with an active subscription on each day, per product

totalSubscribers counts readers, not subscriptions: a reader with two subscriptions to the same product counts once for that product.

Get a Metric Over Time ​

bash
curl "https://api2.sesamy.com/management/stats/series/totalSubscribers?fromDate=2026-01-01&toDate=2026-01-02" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
ParameterTypeDescription
metricstringOne of the metrics, in the path
fromDatestringStart of the range, inclusive, as YYYY-MM-DD
toDatestringEnd of the range, inclusive, as YYYY-MM-DD. Not before fromDate
json
{
  "vendorId": "acme",
  "metric": "totalSubscribers",
  "dateRange": { "fromDate": "2026-01-01", "toDate": "2026-01-02" },
  "title": "Total subscribers",
  "description": "Subscribers with an active subscription on each day in the range, per product.",
  "unit": "count",
  "currency": null,
  "headline": 1840,
  "series": [
    {
      "key": "ACME Plus",
      "points": [
        { "date": "2026-01-01", "value": 1212 },
        { "date": "2026-01-02", "value": 1219 }
      ]
    },
    {
      "key": "ACME Premium",
      "points": [
        { "date": "2026-01-01", "value": 618 },
        { "date": "2026-01-02", "value": 621 }
      ]
    }
  ]
}
FieldDescription
unitHow to read headline and each value: currency for money, count for a number of readers
currencyThe ISO 4217 currency when unit is currency, for example SEK. null for counts
headlineOne summary figure for the whole range, or null when there is none
seriesOne entry per product, named by key. Empty for headline-only metrics such as totalSales

Money is in major units: 145680.35 is 145,680.35 SEK. A point's value is null for a day with no data.

Get an Attribution Breakdown ​

A breakdown groups purchases by one tracking dimension and reports sessions, readers, transactions, conversion rate, and revenue for each value:

bash
curl "https://api2.sesamy.com/management/stats/breakdown/utm_source?fromDate=2026-01-01&toDate=2026-03-31&subset=subscriptions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
ParameterTypeDescription
dimensionstringOne of the dimensions, in the path
fromDatestringStart of the range, inclusive, as YYYY-MM-DD
toDatestringEnd of the range, inclusive, as YYYY-MM-DD
subsetstring(Optional) all (default), subscriptions for recurring purchases only, or single for one-off
limitinteger(Optional) Rows to return, highest revenue first. Defaults to 100, at most 1,000
json
{
  "vendorId": "acme",
  "dimension": "utm_source",
  "subset": "subscriptions",
  "dateRange": { "fromDate": "2026-01-01", "toDate": "2026-03-31" },
  "title": "Metrics by UTM source",
  "description": "Groups purchases by the `utm_source` tag on the originating visit.",
  "rows": [
    {
      "key": "newsletter",
      "label": "newsletter",
      "sessions": 10216,
      "users": 4896,
      "transactions": 2206,
      "conversionRate": 21.59,
      "revenue": { "SEK": 139956, "NOK": 198 }
    }
  ],
  "totals": {
    "sessions": 10216,
    "users": 4896,
    "transactions": 2206,
    "revenue": { "SEK": 139956, "NOK": 198 }
  },
  "rowCount": 1,
  "truncated": false
}

Rows are sorted by revenue, then transactions. revenue is per currency, in major units, and only lists currencies with sales in the range. conversionRate is a percentage from 0 to 100. Purchases without a value for the dimension are grouped in a row whose key is null.

Totals after truncation

When truncated is true, limit dropped rows and totals covers only the rows returned. rowCount is the number of rows before the limit. Raise limit to get complete totals. When rowCount is above 1,000, the most limit allows, no single request returns complete totals: narrow the date range instead.

Dimensions ​

DimensionGroups purchases by
utm_sourceThe utm_source tag of the visit
utm_mediumThe utm_medium tag
utm_campaignThe utm_campaign tag
utm_contentThe utm_content tag
utm_source_mediumThe utm_source and utm_medium pair
referrerThe HTTP referrer of the visit
item_sourceThe page the visit came from
sectionThe section tags of the article
tagThe content tags of the article
authorThe author of the article, as set in your CMS

Rows for item_source, section, tag, and author carry a meta object with page details such as the title, URL, and author.

Discover Metrics and Dimensions ​

GET /management/stats/catalogue returns every metric and dimension with a title and description. Use it to build a picker in your own tools instead of hard-coding the lists above.

bash
curl https://api2.sesamy.com/management/stats/catalogue \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Errors ​

StatusWhen
400An unknown metric or dimension, a date not in YYYY-MM-DD form, or fromDate after toDate
401A missing or invalid token
403The token lacks stats:views:read

Successful series and breakdown responses carry Cache-Control: private, max-age=300, so your HTTP client may reuse them for up to five minutes. The catalogue can be reused for an hour.

Next Steps ​

Released under the MIT License.