Aggregates - Dealroom API

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

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

The aggregate endpoints share the same filter expression syntax as the entity endpoints — every filter you can apply to /api/entities also applies here.

Single-metric aggregate

GET /api/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/entities`. See 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

curl "https://api-next.beta.dealroom.co/api/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"

{
  "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

GET /api/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

curl "https://api-next.beta.dealroom.co/api/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:

{
  "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

curl "https://api-next.beta.dealroom.co/api/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:

{
  "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)

GET /api/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

curl "https://api-next.beta.dealroom.co/api/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"

{
  "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 for full parameter and response schemas.

Endpoint	What it returns
`GET /api/funding-analytics/round-transitions`	From → to stage transitions per company with median days between rounds
`GET /api/funding-analytics/funnel`	Companies bucketed into 9 capital-phase buckets (`$0-1M` through `$2B+`), broken down by dimension
`GET /api/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. To list available values for any filterable dimension at runtime, call GET /api/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.
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).

Documentation Index

​When to use aggregates vs raw entities

​Single-metric aggregate

​Path parameter

​Query parameters

​Example — top 10 countries by deal count, 2024

​Multi-metric aggregate

​Query parameters

​Example — hero stats for the funding dashboard

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

​Heatmap (2D cross-tabulation)

​Query parameters

​Example — funding by year × sector

​Other analytics endpoints

​Available dimensions

​Performance tips

When to use aggregates vs raw entities

Single-metric aggregate

Path parameter

Query parameters

Example — top 10 countries by deal count, 2024

Multi-metric aggregate

Query parameters

Example — hero stats for the funding dashboard

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

Heatmap (2D cross-tabulation)

Query parameters

Example — funding by year × sector

Other analytics endpoints

Available dimensions

Performance tips