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

# Revenue

> How Sacra models and surfaces revenue data for private companies

Sacra surfaces revenue data through two distinct but complementary structures: **revenue datasets**, which are Sacra's own revenue models for each company, and **metric observations**, which are individual datapoints cited to published sources. Both are available through the API and serve different use cases. To work with datasets in code, see [Working with Datasets & Revenue Data](/guides/working-with-datasets).

## Revenue datasets

A revenue dataset is Sacra's internal revenue model for a company. It represents a complete, normalized time series of revenue — year by year from the company's earliest tracked period through the current month — with no gaps.

The purpose of the dataset is to give you a single clean series you can plot, compare, or sync without needing to reconcile inconsistent data from multiple sources. Sacra fills gaps using its own estimates, clearly distinguished from observed figures.

### Structure

Each dataset has a `data_type` that determines what the values represent:

| Data type             | Description                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Revenue**           | Trailing revenue — total amount generated for the given period.                                                               |
| **Recurring Revenue** | Annual recurring revenue (ARR) — the contracted subscription value as of the given date, specific to subscription businesses. |
| **Run Rate Revenue**  | Annualized revenue as of the given date, regardless of business model.                                                        |

### Datapoint periods

Each datapoint in a dataset has a date that encodes its period type:

* **December 31** — a full year-end figure for that calendar year.
* **Any other month-end** — a year-to-date figure through that month.

A revenue value dated `2024-04-30` means cumulative revenue from January 2024 through April 2024 — not a trailing 12-month figure. A value dated `2024-12-31` means the full-year total.

```json theme={null}
{ "x": "2023-12-31T00:00:00.000Z", "y": 170000000, "type": "historical" }
{ "x": "2024-04-30T00:00:00.000Z", "y": 39600000, "type": "historical" }
```

<Tip>If the date falls on December 31, treat it as a full-year figure. Any other month-end date is year-to-date.</Tip>

### How revenue types interact with periods

**Revenue** reflects total amounts generated — either for the full year (year-end) or from January 1 through the given month (year-to-date). It does not represent a trailing 12-month window.

**Run Rate Revenue** is a forward-looking annualized figure regardless of period type, roughly the most recent month's revenue multiplied by 12. A run rate dated June 2025 implies June 2025 revenue × 12.

**Recurring Revenue (ARR)** applies specifically to subscription businesses — it's the annual recurring revenue as of the given date, based on contracted subscription value rather than an annualization of recent revenue.

***

## Metric observations

A metric observation is a single revenue or growth datapoint that Sacra has extracted and cited to a specific published source — a news article, earnings call, SEC filing, or industry report from a trusted publication.

Where datasets give you a complete modeled series, observations give you the raw evidence behind specific claims. Each observation is precise, sourced, and structured for programmatic use.

### Structure

Each observation has a `metric_definition` describing what is being measured and a `measurement` carrying the numeric claim:

**`metric_definition`**

| Field                  | Description                                                                                                          |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `base`                 | Metric family: `trailing_revenue`, `run_rate_revenue`, or `recurring_revenue`                                        |
| `view`                 | `value` — a point value or range; `growth` — a growth rate or multiple                                               |
| `base_period`          | Granularity of the measured window: `year`, `quarter`, `month`, `ytd`, `custom`                                      |
| `base_forward`         | Forward anchor for ARR and run rate metrics — typically `year` for annualized framing, `month` for MRR-style framing |
| `growth_period`        | Comparator cadence for growth rows: `year`, `quarter`, `month`, `ytd`, `custom`                                      |
| `growth_period_length` | Number of comparator periods — `1` is standard; values above 1 indicate multi-period windows like 3-year CAGR        |

**`measurement`**

| Field                                 | Description                                                                                  |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| `scenario`                            | `historical` — observed/realized; `projection` — forecast                                    |
| `end_date`                            | Anchor date for the datapoint                                                                |
| `custom_start_date`                   | Explicit start of the primary measured window, when the window is non-standard               |
| `comparison_window_end_date`          | End date of the comparison baseline for growth rows — required when `view` is `growth`       |
| `comparison_window_custom_start_date` | Custom start of the comparison window, when the baseline is non-standard                     |
| `type`                                | Numeric shape: `equals`, `greater_than`, `less_than`, or `range`                             |
| `amount` / `low` / `high`             | Raw numeric values — no symbols, formatting comes from `unit_kind`                           |
| `unit_kind`                           | `currency`, `percent`, `multiple`, or `count`                                                |
| `scope_name` / `scope_type`           | If set, the datapoint refers to a segment rather than the whole company                      |
| `status`                              | Lifecycle status of the datapoint — the `/metrics` endpoint returns active observations only |

### Numeric shapes

| `measurement.type` | Read as                  |
| ------------------ | ------------------------ |
| `equals`           | Exactly `amount`         |
| `greater_than`     | More than `low`          |
| `less_than`        | Less than `high`         |
| `range`            | Between `low` and `high` |

<Note>`amount`, `low`, and `high` are raw numeric values with no symbols. Display formatting comes from `unit_kind` (and `currency_code` when `unit_kind` is `currency`) combined with `measurement.type`.</Note>

### Citations

Every observation includes a `citations` object with the sources backing the claim:

* `citations.sources[]` — deduplicated list of source URLs, each with an optional `quote` field containing the extracted text that supports the datapoint
* `citations.summary.count` — number of unique sources for this observation

`quote: null` does not mean the source is invalid — SEC filing URLs are included by default even without an extracted quote.

### Growth observations

Growth rows (`view: "growth"`) require a `comparison_window_end_date` to define the baseline:

| Case        | `end_date`   | `comparison_window_end_date` |
| ----------- | ------------ | ---------------------------- |
| FY2025 YoY  | `2025-12-31` | `2024-12-31`                 |
| Q1 2025 YoY | `2025-03-31` | `2024-03-31`                 |
| Q2 2025 QoQ | `2025-06-30` | `2025-03-31`                 |

For growth rows, `unit_kind: "percent"` means percentage growth (e.g. `55` = 55%) and `unit_kind: "multiple"` means an x-multiple (e.g. `3.7` = 3.7×).

### Common patterns

**Forward metrics are point-in-time.** For `run_rate_revenue` and `recurring_revenue`, the datapoint is an anchored forward-looking view as of the given date. `base_forward` carries the annualized or monthly framing; `base_period` is commonly `null` for these.

**`growth_period_length` above 1** indicates a multi-period cumulative growth window rather than a single prior period comparison. `growth_period: year` with `growth_period_length: 3` means a 3-year CAGR-style window; `growth_period: month` with `growth_period_length: 6` means a 6-month CMGR-style window.

**Scoped datapoints** have both `scope_name` and `scope_type` set, indicating the figure applies to a product line or business segment rather than the whole company. If both are null, the datapoint is company-level.

**YTD-vs-YTD growth** (`growth_period: ytd`) compares two year-to-date windows: the current YTD anchored by `end_date` and the prior YTD anchored by `comparison_window_end_date`.

### Field roles at a glance

| Field                                    | Role                                               | What it is not                            |
| ---------------------------------------- | -------------------------------------------------- | ----------------------------------------- |
| `measurement.end_date`                   | Anchor/end date of the primary measured window     | Not automatically the comparison baseline |
| `metric_definition.base_period`          | Granularity of the primary measured window         | Not the growth comparator cadence         |
| `metric_definition.growth_period`        | Comparator cadence for growth rows                 | Not the primary metric window granularity |
| `measurement.comparison_window_end_date` | Explicit baseline anchor for the comparison window | Not optional for growth rows              |

### Null handling

| Field                                             | `null` means                                                                         |
| ------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `metric_definition.base_forward`                  | Not stored as a forward-framed metric                                                |
| `metric_definition.growth_period`                 | Not a growth row (`view` is `value`)                                                 |
| `measurement.custom_start_date`                   | No explicit custom window start                                                      |
| `measurement.comparison_window_end_date`          | For value rows: not applicable. For growth rows: unexpected — this field is required |
| `measurement.comparison_window_custom_start_date` | Comparison window is not custom                                                      |
| `measurement.scope_name` / `scope_type`           | Unscoped — datapoint applies to the whole company                                    |
| `citations.sources[].quote`                       | No extracted quote available — the source URL may still be valid evidence            |