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

# Aggregates

> Compute counts, sums, medians, and percentiles grouped by one or more dimensions via the Dealroom aggregate endpoints — heatmaps, top-N rankings, timeseries, and funnels in one API call.

The Dealroom API exposes composable aggregate endpoints that compute grouped metrics
server-side — counts, sums, medians, percentiles — across companies, funding rounds,
valuations, founders, and investors. Use them instead of paging through raw entities when
you want totals, rankings, distributions, or cross-tabulations.

## When to use aggregates vs raw entities

```text theme={null}
Need a per-row dataset?         → /api/data/entities, /api/data/transactions, /api/data/valuations
Need a count, sum, or median?   → /api/analytics/aggregate/:source
Need multiple metrics at once?  → /api/analytics/aggregate/:source/multi-metric
Need a 2D matrix (e.g. heatmap)? → /api/analytics/funding-analytics/heatmap
Need stage transitions?         → /api/analytics/funding-analytics/round-transitions
Need bucketed company totals?   → /api/analytics/funding-analytics/funnel
Need per-entity yearly metrics? → /api/analytics/timeseries
```

The aggregate endpoints share the same [filter expression](/mintlify/concepts/filtering)
syntax as the entity endpoints — every filter you can apply to `/api/data/entities` also
applies here.

## Single-metric aggregate

```text theme={null}
GET /api/analytics/aggregate/:source
```

Groups rows by one or more dimensions and computes a single metric.

### Path parameter

| `source`         | Aggregates over                                   |
| ---------------- | ------------------------------------------------- |
| `companies`      | Entity-level metrics (funding totals, valuations) |
| `funding-rounds` | Per-round metrics (deal counts, round sizes)      |
| `valuations`     | Valuation history                                 |
| `founders`       | Founder counts                                    |
| `investors`      | Investor counts                                   |

### Query parameters

| Param      | Required | Description                                                                                            |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `metric`   | yes      | `count`, `count_distinct:field`, `sum:field`, `avg:field`, `median:field`, `p25:field`, `p75:field`    |
| `group_by` | yes      | Dimension(s), comma-separated for multi-dim: `hq_country`, `year,sector`                               |
| `filter`   | no       | Filter expression — same syntax as `/api/data/entities`. See [Filtering](/mintlify/concepts/filtering) |
| `sort`     | no       | `metric` (prefix `-` for desc) or `dimension`                                                          |
| `limit`    | no       | Max groups returned (default `25`, max `500`)                                                          |
| `currency` | no       | ISO 4217 code for monetary metric conversion. Defaults to USD.                                         |

### Example — top 10 countries by deal count, 2024

```bash theme={null}
curl "https://api-next.dealroom.co/api/analytics/aggregate/funding-rounds?metric=count&group_by=hq_country&filter=year[eq]:2024&sort=-count&limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

```json theme={null}
{
  "data": [
    { "dimension": "United States", "count": 12000 },
    { "dimension": "United Kingdom", "count": 3500 },
    { "dimension": "Germany", "count": 2200 }
  ],
  "query_info": {
    "source": "funding-rounds",
    "group_by": "hq_country",
    "metric": "count",
    "total_groups": 180
  }
}
```

## Multi-metric aggregate

```text theme={null}
GET /api/analytics/aggregate/:source/multi-metric
```

Compute multiple labeled metrics in a single call — flat (totals) or grouped (breakdown).
Optionally apply per-metric filters for conditional counting (e.g. "deals" vs "unicorn deals"
in the same query).

### Query parameters

| Param           | Required | Description                                                                |
| --------------- | -------- | -------------------------------------------------------------------------- |
| `metric`        | yes      | Repeated: `metric=label,metric_type` (e.g. `metric=deals,count`)           |
| `group_by`      | no       | Omit for a flat aggregation (returns a one-element array)                  |
| `metric_filter` | no       | Per-metric filter: `label:filter_expression` — only applies to that metric |
| `metric_having` | no       | Post-aggregation filter on a metric value (e.g. `pct[gt]:25`)              |
| `filter`        | no       | Global filter expression applied to every metric                           |
| `sort`          | no       | Sort by metric label (prefix `-` for desc) or `dimension`                  |
| `limit`         | no       | Max groups (default `25`, max `500`)                                       |
| `currency`      | no       | ISO 4217 code for monetary metric conversion. Defaults to USD.             |

### Example — hero stats for the funding dashboard

```bash theme={null}
curl "https://api-next.dealroom.co/api/analytics/aggregate/funding-rounds/multi-metric?metric=deals,count&metric=funding,sum:amount_usd&metric=companies,count_distinct:entity_id&filter=year[gte]:2024" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

Flat response (no `group_by`) — `data` is a single-element array, matching the
shape of the grouped response so clients can use one parser for both:

```json theme={null}
{
  "data": [
    {
      "deals": 45000,
      "funding": 150000000000,
      "companies": 28000
    }
  ],
  "query_info": {
    "source": "funding-rounds",
    "metrics": [
      { "label": "deals", "type": "count" },
      { "label": "funding", "type": "sum:amount_usd" },
      { "label": "companies", "type": "count_distinct:entity_id" }
    ]
  },
  "currency": "USD"
}
```

Read totals with `response.data[0].deals` — there's always exactly one row.

### Example — top 5 sectors by total funding, with deal counts

```bash theme={null}
curl "https://api-next.dealroom.co/api/analytics/aggregate/funding-rounds/multi-metric?metric=deals,count&metric=funding,sum:amount_usd&group_by=sector&sort=-funding&limit=5" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

Grouped response:

```json theme={null}
{
  "data": [
    { "dimension": "Fintech", "deals": 5000, "funding": 30000000000 },
    { "dimension": "AI/ML", "deals": 3000, "funding": 20000000000 },
    { "dimension": "Health", "deals": 2500, "funding": 15000000000 }
  ],
  "query_info": {
    "source": "funding-rounds",
    "group_by": "sector",
    "metrics": [
      { "label": "deals", "type": "count" },
      { "label": "funding", "type": "sum:amount_usd" }
    ],
    "total_groups": 45
  }
}
```

## Heatmap (2D cross-tabulation)

```text theme={null}
GET /api/analytics/funding-analytics/heatmap
```

Two-dimensional grouping with per-axis top-N filtering and sparse-matrix output. Use when
you want a `year × sector` or `country × stage` matrix for a heatmap visualisation.

### Query parameters

| Param      | Required | Default | Description                                                             |
| ---------- | -------- | ------- | ----------------------------------------------------------------------- |
| `x`        | yes      | —       | X-axis dimension key                                                    |
| `y`        | yes      | —       | Y-axis dimension key                                                    |
| `metric`   | no       | `count` | `count`, `company_count`, `total_amount`, `avg_amount`, `median_amount` |
| `top_n_x`  | no       | `15`    | Max X-axis categories (1–50)                                            |
| `top_n_y`  | no       | `15`    | Max Y-axis categories (1–50)                                            |
| `filter`   | no       | —       | Filter expression                                                       |
| `currency` | no       | `USD`   | ISO 4217 code for monetary metric conversion                            |

Available dimensions: `round_year`, `round_quarter`, `round_type`, `standardized_round`,
`amount_range`, `stage`, `country`, `continent`, `city`, `region`, `sector`,
`standardized_sector`, `technology`, `industry_tags`, `business_model`, `income_stream`,
`client_focus`, `investor_type`, `investor_country`, `investor_continent`.

### Example — funding by year × sector

```bash theme={null}
curl "https://api-next.dealroom.co/api/analytics/funding-analytics/heatmap?x=round_year&y=sector&metric=total_amount&top_n_x=4&top_n_y=3" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

```json theme={null}
{
  "x_labels": ["2020", "2021", "2022", "2023"],
  "y_labels": ["Fintech", "AI/ML", "SaaS"],
  "cells": [
    [0, 0, 1500000],
    [0, 1, 2300000],
    [1, 0, 1800000]
  ],
  "x_totals": [5000000, 8000000, 7000000, 6000000],
  "y_totals": [10000000, 8000000, 5000000],
  "grand_total": 23000000,
  "meta": {
    "metric": "total_amount",
    "x_dimension": "round_year",
    "y_dimension": "sector",
    "total_rows": 50000
  }
}
```

`cells` is sparse — only non-zero `[x_index, y_index, value]` triples are returned.
`x_totals` / `y_totals` are the marginal totals along each axis.

## Other analytics endpoints

These return purpose-built shapes that can't be expressed via the generic aggregates. See
the [API Reference](/api-reference) for full parameter and response schemas.

| Endpoint                                                 | What it returns                                                                                    |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `GET /api/analytics/funding-analytics/round-transitions` | From → to stage transitions per company with median days between rounds                            |
| `GET /api/analytics/funding-analytics/funnel`            | Companies bucketed into 9 capital-phase buckets (`$0-1M` through `$2B+`), broken down by dimension |
| `GET /api/analytics/timeseries`                          | Yearly metrics (employees, revenue, valuation) per entity                                          |

## Available dimensions

Available dimensions vary by source. Across all aggregate endpoints, common dimension
groups:

| Category      | Dimensions                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| Location      | `hq_country`, `hq_city`, `hq_state`, `hq_continent`, `macro_region`, `region`                                |
| Time          | `year`, `quarter`, `launch_year`                                                                             |
| Taxonomy      | `sector`, `technology`, `industry`, `sub_industry`, `business_model`, `income_stream`, `client_focus`, `sdg` |
| Funding       | `round_type`, `standardized_round`, `amount_range`                                                           |
| Investor      | `investor_type`, `investor_country`, `investor_continent`                                                    |
| Entity status | `company_status`                                                                                             |

For the full list of dimensions exposed by each endpoint, check the
[API Reference](/api-reference). To list available values for any filterable
dimension at runtime, call `GET /api/reference/filters/{key}/values` (where `{key}` is
the filter key, e.g. `location`, `tag_id`, `growth_stage`).

## Performance tips

* Always filter before aggregating. An unfiltered aggregate on a large source can hit the
  15s [query timeout](/mintlify/concepts/errors#query-timeout).
* Prefer the multi-metric endpoint over multiple single-metric calls — fewer round trips,
  a single SQL query server-side.
* For dashboard-style views, fan out 3–8 aggregate calls in parallel from your client. Each
  query is small and independently cacheable.
* Use `count_distinct:entity_id` when you want unique-company counts across rounds (rather
  than the deal count `count`).