Developers

Honest MRR metrics API

Every report in the dashboard is also available as JSON, so you can put your MRR in a spreadsheet, a board deck or your own tooling — and two CSV endpoints let a script feed in revenue and ad spend that no API exposes. The machine-readable description is at /openapi.json (OpenAPI 3.1, with an example response for every report), and /.well-known/api-catalog lists it for tools that look there.

Authentication

Create an API key in the app under Settings → API & sharing. It is shown once and stored only as a hash, so copy it then. Send it on every request:

curl https://honestmrr.com/api/v1/mrr \
  -H "Authorization: Bearer hm_live_…"

Keys are read-only unless you tick “Allow imports (write)” when you create one — the import endpoints refuse read-only keys with a 403. A key belongs to one organization and reads only that organization's data; revoke it from the same page and it stops working at once. A request without a valid key gets a 401 that links back to this page.

Reports

GET /api/v1/<report> returns { "report", "generatedAt", "data" }. Money is in your reporting currency's minor units (cents for USD) unless a field says otherwise, computed with the same rules as the dashboard — they are written out on how we calculate MRR.

/api/v1/overview — Headline numbers: MRR, 30-day movements, customers, churn and growth.
/api/v1/mrr — The MRR series with each month's new, expansion, contraction, churn and reactivation.
/api/v1/churn — Logo churn, gross and net revenue churn, month by month.
/api/v1/revenue — Realized revenue — cash collected, net of refunds — month by month.
/api/v1/acquisition — Ad spend, new customers, CAC, payback and LTV:CAC (LTV fields are null below Pro).

Imports

For revenue and ad spend without an API, post the platform's CSV export as multipart/form-data with a write-scope key. Files are at most 8 MB; re-importing the same file adds nothing twice.

curl -X POST https://honestmrr.com/api/v1/import/revenue \
  -H "Authorization: Bearer hm_live_…" \
  -F source=youtube -F [email protected]

/api/v1/import/revenue takes source: amazon_associates, youtube, tiktok_creator, instagram_creator, facebook_creator, onlyfans. Imported revenue is realized revenue on its own line — it never enters MRR.

/api/v1/import/ad-spend takes platform: google_ads, facebook_ads, instagram_ads, tiktok_ads, microsoft_ads. Spend feeds CAC and payback.

Limits and errors

Each key may make 60 requests a minute, and each IP address 240; past either, the response is a 429 whose Retry-After header gives the seconds until the one-minute window resets.

These errors come back as JSON, { "error": "…" }: 400 for an import that isn't multipart/form-data or is missing a field, 401 for a missing or revoked key, 403 for a read-only key on an import, 404 for an unknown report, 413 for a file over 8 MB, 422 for a file that couldn't be read as that source's CSV, 429 for the rate limit, and 500 if an import fails on our side — retrying the same file is safe, because imports are idempotent.

Questions

Missing a report you need? Email us and a person answers.