> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marginfront.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics · MRR

> Monthly recurring revenue. Three variants: last calendar month billed, run-rate, and contractual floor

# MRR analytics

`GET /v1/analytics/mrr` is the single place to read monthly recurring revenue (MRR) out of MarginFront. It returns one of three MRR variants, or all three at once. Use it when you need to answer:

* "What did we actually bill for last month?"
* "If the last 30 days kept going, what would we bill per month?"
* "What is the contractual floor we will bill regardless of usage?"
* "How does a single customer (or subscription) contribute to each of those?"

Each variant answers a different question. They can and do produce different numbers. Pick the one that matches what you are trying to show.

This is a read-only endpoint.

***

## The endpoint

**Method and URL:**

```
GET /v1/analytics/mrr
```

Auth: API key in the `x-api-key` header.

***

## Query parameters

| Param            | Type   | Required | Description                                                                                           |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `variant`        | string | no       | Which MRR variant to return. One of `canonical`, `runRate`, `committed`, `all`. Default: `canonical`. |
| `customerId`     | UUID   | no       | Narrow to one customer. Use MarginFront's internal customer UUID, not your `externalId`.              |
| `subscriptionId` | UUID   | no       | Narrow to one subscription.                                                                           |

***

## The three MRR variants

### `canonical` (last-calendar-month billed)

**Plain English:** "What did we actually bill last calendar month?"

Looks at non-draft invoices whose invoice date lands in the most recent complete calendar month. Sums the totals. That is your MRR. This is a backward-looking number based on what finance actually sent out.

Good for: finance reporting, board decks, anything where "actual billed" is what you want.

### `runRate` (last 30 days, monthly-normalized)

**Plain English:** "If the current pace keeps going, what would we bill per month?"

For each active subscription: take recurring fees plus seat fees plus actual usage from the last 30 days, and normalize everything to a monthly number (yearly subs get divided by 12). Add it up across every active subscription. That is run-rate MRR.

Good for: forecasting, growth dashboards, anything where you want the forward-looking trajectory.

### `committed` (contractual floor)

**Plain English:** "What will we bill per month even if usage goes to zero?"

Same shape as run-rate, but actual usage is replaced with the subscription's `minimumCommitment` times its rate (zero if no minimum is set). So it strips out variability and shows only what is guaranteed by contract.

Good for: revenue predictability, churn-risk analysis, anything where you want to see the floor.

### `all`

Returns all three variants in one response. Use this when you need to render a comparison (e.g., a dashboard tile showing all three side by side).

***

## Example curl calls

**Last calendar month's billed MRR (default):**

```bash theme={null}
curl "https://api.marginfront.com/v1/analytics/mrr" \
  -H "x-api-key: mf_sk_test_..."
```

**Run-rate MRR for one customer:**

```bash theme={null}
curl "https://api.marginfront.com/v1/analytics/mrr?variant=runRate&customerId=bc8eceda-50e4-4138-b2a2-47e92d344540" \
  -H "x-api-key: mf_sk_test_..."
```

**All three variants at once:**

```bash theme={null}
curl "https://api.marginfront.com/v1/analytics/mrr?variant=all" \
  -H "x-api-key: mf_sk_test_..."
```

***

## What you get back (`200 OK`)

### `variant=canonical`

```json theme={null}
{
  "variant": "canonical",
  "mrr": 12480.75,
  "arr": 149769.0
}
```

* **`mrr`** is last calendar month's non-draft invoice total.
* **`arr`** is `mrr × 12`.

### `variant=runRate`

```json theme={null}
{
  "variant": "runRate",
  "mrr": 13842.5,
  "breakdown": [
    {
      "subscriptionId": "9a8b7c6d-...",
      "customerId": "5e7f8a3d-...",
      "agentId": "b47e12fa-...",
      "planId": "a1b2c3d4-...",
      "recurring": 299.0,
      "seatBased": 50.0,
      "usage": 493.5,
      "total": 842.5
    }
  ]
}
```

* **`mrr`** is the sum of `total` across every active subscription.
* **`breakdown`** is one row per active subscription.
* **`recurring`** is the recurring-fee contribution, monthly-normalized (yearly subs divided by 12).
* **`seatBased`** is the seat-fee contribution: `max(seatsCount, minimumCommitment) × rate`, monthly-normalized.
* **`usage`** is actual last-30-days usage revenue for the subscription.
* **`total`** is `recurring + seatBased + usage` (the sub's run-rate MRR contribution).

### `variant=committed`

```json theme={null}
{
  "variant": "committed",
  "mrr": 10948.0,
  "breakdown": [
    {
      "subscriptionId": "9a8b7c6d-...",
      "customerId": "5e7f8a3d-...",
      "agentId": "b47e12fa-...",
      "planId": "a1b2c3d4-...",
      "recurring": 299.0,
      "seatBased": 50.0,
      "usage": 200.0,
      "total": 549.0
    }
  ]
}
```

Same fields as `runRate`, but `usage` is replaced with the strategy's contractual floor (`minimumCommitment × rate`, or `0` if no minimum is set).

### `variant=all`

```json theme={null}
{
  "variant": "all",
  "canonical": {
    "mrr": 12480.75,
    "arr": 149769.0
  },
  "runRate": {
    "mrr": 13842.5,
    "breakdown": []
  },
  "committed": {
    "mrr": 10948.0,
    "breakdown": []
  }
}
```

All three variants nested under one response.

All money fields are `number`, not strings.

***

## When to use this vs. other endpoints

Use **this endpoint** when you specifically want MRR or ARR.

Use [`/v1/analytics/revenue`](./analytics-revenue) when you want revenue for an arbitrary window (not a monthly roll-up), with cost and margin attached.

Use [`/v1/invoices`](./invoices) when you want the individual invoice records that make up the `canonical` MRR total.

***

## Using the Node SDK

```typescript theme={null}
import { MarginFrontClient } from "@marginfront/sdk";

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

// Last calendar month's billed MRR
const { mrr, arr } = await mf.analytics.mrr();
console.log(`MRR: $${mrr}, ARR: $${arr}`);

// Run-rate MRR with per-subscription breakdown
const runRate = await mf.analytics.runRateMrr();
console.log(`Run-rate MRR: $${runRate.mrr}`);
for (const row of runRate.breakdown) {
  console.log(`  sub ${row.subscriptionId}: $${row.total}/mo`);
}

// Committed MRR (contractual floor)
const committed = await mf.analytics.committedMrr();
console.log(`Committed floor: $${committed.mrr}`);
```

See the [SDK analytics page](/sdk/analytics) for all seven analytics methods.

***

## Common errors

* **`400 Bad Request`**: `variant` is not one of `canonical`, `runRate`, `committed`, `all`, or a UUID filter is invalid.
* **`401 Unauthorized`**: API key missing or wrong.