# saas_metrics

Read recurring revenue, retention, margin, burn and runway metrics for a month, quarter or year. Month-only metrics use recorded month-end contract history.

## What it shows

ARR, MRR, ACV, run rate, gross margin, burn, runway and CAC for a year, quarter or month; at month granularity also the net-new-ARR waterfall, NRR, GRR, logo churn, burn multiple, rule of 40 and LTV, from month-end MRR derived from the contract history. Without currency, the window must fit one functional-currency period; pass currency for an explicit native-ledger view across a change.

## Example MCP App view

The read-only example below uses illustrative demo data and the same report component as the MCP App. These are not your books or the result of the request example.

<iframe class="docs-report-preview" src="/docs/report-previews/saas_metrics.html" title="saas_metrics report view with demo data" loading="lazy" sandbox referrerpolicy="no-referrer"></iframe>

[Open the full example view](/docs/report-previews/saas_metrics.html).

## Inputs

Send the fixed `kind` and these parameters at the top level of the report request, not inside `input`. Omitting as_of uses the server's current time.

Required means required within its containing object; an optional parent can be omitted.

| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
| `year` | integer | Yes | Calendar year (not the business fiscal year); quarter is a calendar quarter. Minimum: `2000`. Maximum: `2100`. Example: `2026`. |
| `month` | integer | No | Month; exclusive with quarter. Minimum: `1`. Maximum: `12`. Example: `9`. |
| `quarter` | integer | No | Quarter; exclusive with month. Minimum: `1`. Maximum: `4`. |
| `currency` | string | No | Ledger currency (default: the functional currency active for the report period). Format: currency. |
| `as_of` | string | No | The date (YYYY-MM-DD) or UTC timestamp (RFC 3339) the report is taken at. A date is a UTC day and includes everything on it; a timestamp includes everything before that moment. A calendar date includes the whole UTC day (exclusive cutoff); an explicit timestamp keeps the stated instant. Format: moment. |
| `trend` | boolean | No | true adds a 12-month series per supported metric ending at the month (month granularity only).  |

## Reading the result

Running this report does not change the books. Its description above distinguishes recorded-book summaries from previews based on supplied facts or assumptions. Interpret its totals, grouping, missing-data indicators and pagination using that description. Monetary amounts are integer strings in the reported unit; ratios and assumptions can be fractional numbers. An empty result is not evidence that the business had no activity.

The public OpenAPI contract does not enumerate this report's result fields. Fetch `GET /v1/reports` for its live description and parameters, and inspect the returned JSON rather than assuming an output shape.

## Example request


```json
{
  "kind": "saas_metrics",
  "year": 2026,
  "month": 9
}
```


[All reports](/docs/report-reference/) · [Operation and errors](/docs/api-reference/operations/reports-run/) · [Reusable schemas](/docs/api-reference/components/)

Keep credentials out of prompts; rehearse writes only in a disposable sandbox.

## Exact request schema


```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "kind": {
      "const": "saas_metrics"
    },
    "year": {
      "description": "Calendar year (not the business fiscal year); quarter is a calendar quarter.",
      "type": "integer",
      "minimum": 2000,
      "maximum": 2100
    },
    "month": {
      "description": "Month; exclusive with quarter.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    },
    "quarter": {
      "description": "Quarter; exclusive with month.",
      "type": "integer",
      "minimum": 1,
      "maximum": 4
    },
    "currency": {
      "description": "Ledger currency (default: the functional currency active for the report period).",
      "type": "string",
      "minLength": 1
    },
    "as_of": {
      "description": "The date (YYYY-MM-DD) or UTC timestamp (RFC 3339) the report is taken at. A date is a UTC day and includes everything on it; a timestamp includes everything before that moment.",
      "type": "string",
      "minLength": 1
    },
    "trend": {
      "description": "true adds a 12-month series per supported metric ending at the month (month granularity only).",
      "type": "boolean"
    }
  },
  "required": [
    "kind",
    "year"
  ]
}
```