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/cataloguelists 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.comAuthentication
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_TOKENSee Authentication for how to obtain a token.
Metrics
| Metric | Unit | Description |
|---|---|---|
currentMrr | currency | Monthly recurring revenue as of each day, per product |
newMrr | currency | Recurring revenue added by new subscriptions on each day |
churnMrr | currency | Recurring revenue lost to cancellations on each day |
projectedMrr | currency | Projected monthly recurring revenue for each day |
totalRevenue | currency | All revenue recognised in the range, recurring and one-off |
totalSales | currency | Total value of sales in the range. Headline figure only, with no series |
subscriptionSales | currency | Sales value from subscriptions on each day |
totalSubscribers | count | Subscribers 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
curl "https://api2.sesamy.com/management/stats/series/totalSubscribers?fromDate=2026-01-01&toDate=2026-01-02" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"| Parameter | Type | Description |
|---|---|---|
metric | string | One of the metrics, in the path |
fromDate | string | Start of the range, inclusive, as YYYY-MM-DD |
toDate | string | End of the range, inclusive, as YYYY-MM-DD. Not before fromDate |
{
"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 }
]
}
]
}| Field | Description |
|---|---|
unit | How to read headline and each value: currency for money, count for a number of readers |
currency | The ISO 4217 currency when unit is currency, for example SEK. null for counts |
headline | One summary figure for the whole range, or null when there is none |
series | One 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:
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"| Parameter | Type | Description |
|---|---|---|
dimension | string | One of the dimensions, in the path |
fromDate | string | Start of the range, inclusive, as YYYY-MM-DD |
toDate | string | End of the range, inclusive, as YYYY-MM-DD |
subset | string | (Optional) all (default), subscriptions for recurring purchases only, or single for one-off |
limit | integer | (Optional) Rows to return, highest revenue first. Defaults to 100, at most 1,000 |
{
"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
| Dimension | Groups purchases by |
|---|---|
utm_source | The utm_source tag of the visit |
utm_medium | The utm_medium tag |
utm_campaign | The utm_campaign tag |
utm_content | The utm_content tag |
utm_source_medium | The utm_source and utm_medium pair |
referrer | The HTTP referrer of the visit |
item_source | The page the visit came from |
section | The section tags of the article |
tag | The content tags of the article |
author | The 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.
curl https://api2.sesamy.com/management/stats/catalogue \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Errors
| Status | When |
|---|---|
400 | An unknown metric or dimension, a date not in YYYY-MM-DD form, or fromDate after toDate |
401 | A missing or invalid token |
403 | The 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
- Generating Reports: export raw data as files
- Listing Checkouts: look up individual purchases
- Error Handling
- Management API reference