API documentation

Create a key in Settings → API keys and send it on every request. Keys are shown once and stored hashed; revoke them from the same place.

curl -H "Authorization: Bearer ko_…" \
  "https://kometrics.com/api/v1/metrics/all?start-date=2026-01-01&end-date=2026-08-07"

HTTP Basic with the key as username (empty password) also works, so existing subscription-analytics client libraries can be pointed here unchanged. Errors are { "code": 422, "message": "…" } with a matching HTTP status.

Conventions: money is integer USD cents, rates are percent floats, dates are YYYY-MM-DD in the account timezone. Machine-readable contract: GET /api/v1/openapi.json (no auth required).

{ "name": "Templated", "currency": "USD", "time_zone": "America/Sao_Paulo", "week_start_on": "monday" }

all returns every metric per period; mrr adds the five movement components (new business, expansion, contraction, churn, reactivation); the rest return {date, value} pairs. Every response carries a summary with current/previous/percentage-change. The in-progress period's churn rates are extrapolated to a full period, exactly as in the UI.

{
  "entries": [
    { "date": "2026-07-31", "mrr": 2012559, "arr": 24150708, "customers": 342, … },
    { "date": "2026-08-07", "mrr": 2030827, "arr": 24369924, "customers": 345, … }
  ],
  "summary": { "current": 2030827, "previous": 2012559, "percentage-change": 0.91 }
}

{
  "entries": [
    { "external_id": "cus_…", "name": "Castioni D Ltda", "email": "…", "country": "BR",
      "source": "stripe", "status": "active", "mrr": 13392, "arr": 160704,
      "customer-since": "2025-09-17", "last-activity": "2026-07-18" }
  ],
  "cursor": "MTIzNA", "has_more": true
}

Workspaces with privacy mode on return "anonymized": true per entry instead of email, and name is a stable pseudonym.

{
  "external_id": "cus_…", "name": "…", "status": "active",
  "customer-since": "2025-09-17", "subscriber-since": "2025-09-18",
  "mrr": 13392, "arr": 160704, "net-payments": 109407,
  "subscriptions": [
    { "external_id": "sub_…", "plan": "New BRL Price (Jun 2025)", "interval": "monthly",
      "mrr": 13392, "status": "active", "started": "2025-09-18",
      "paid-through": "2026-08-18", "cancels-at": null }
  ]
}

Sub-resources: /activities (the customer's MRR movements) and /invoices (with integer-cent totals), both newest first.

{
  "entries": [
    { "id": 2139, "type": "expansion", "date": "2026-07-18", "mrr-movement": 114,
      "mrr": 13392, "customer-external-id": "cus_…", "subscription-external-id": "sub_…" }
  ],
  "cursor": "…", "has_more": true
}