> ## 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.

# Multi-metric aggregate

> Return multiple labeled metrics from a single SQL query, each with optional per-metric
filters using aggregate FILTER (WHERE ...) clauses. Supports all metric types (COUNT, SUM,
AVG, MEDIAN, MAX) and optional dimensional grouping (group_by).

**Metric param format:** `metric=<label>,<metric_type>`
- First segment = label (lowercase alphanumeric + underscore)
- Second segment = metric type (e.g., `count`, `sum:total_funding`, `percentage:label_a/label_b`)

**Percentage metrics** (`percentage:numerator/denominator`): Computes `ROUND(numerator * 100.0 / NULLIF(denominator, 0), 2)`.
- Both referenced labels must be defined as non-percentage metrics in the same request.
- Percentage metrics cannot have per-metric filters (apply filters to the referenced metrics instead).
- Example: `metric=filtered,count&metric=total,count&metric=pct,percentage:filtered/total`

**Per-metric filters** (`metric_filter` param): `metric_filter=<label>:<filter_expression>`
- Uses the same AST filter syntax as the shared `filter` param
- Example: `metric_filter=unicorns:is_unicorn[eq]:true`
- Compound: `metric_filter=funded:and(total_funding[gte]:100000,is_vc_backed[eq]:true)`

**group_by** (optional): Dimension(s) to group by, comma-separated.
**sort** (optional): Sort by metric label or `dimension`. Prefix `-` for descending (default).
**limit** (optional): Max results when grouped (1-500, default 25).

**Post-aggregation filter** (`metric_having` param): Filter grouped rows by metric values.
- Format: `metric_having=<label>[op]:<value>` where op is gt, gte, lt, lte, eq, neq
- Repeatable for multiple conditions (AND semantics)
- Only valid when `group_by` is present
- Example: `metric_having=percentage[gt]:25&metric_having=filtered[gte]:5`

**Shared filters** (`filter` param): Uses structured AST syntax, same as `/api/analytics/aggregate/:source`.
- Single filter: `filter=tag_id[eq]:42`
- AND: `filter=and(tag_id[eq]:42,launch_year[gte]:2020)`
- OR: `filter=or(hq_location[eq]:133,hq_location[eq]:75)`

**Example — mixed metrics with group_by:**
```
GET /api/analytics/aggregate/companies/multi-metric
  ?metric=total,count
  &metric=unicorns,count
  &metric=unicorn_funding,sum:total_funding
  &metric_filter=unicorns:is_unicorn[eq]:true
  &metric_filter=unicorn_funding:is_unicorn[eq]:true
  &group_by=hq_country
  &sort=-total
  &limit=10
  &filter=launch_year[gte]:2015
```

**Example — flat (no group_by):**
```
GET /api/analytics/aggregate/companies/multi-metric
  ?metric=total,count
  &metric=unicorns,count
  &metric=unicorn_funding,sum:total_funding
  &metric_filter=unicorns:is_unicorn[eq]:true
  &metric_filter=unicorn_funding:is_unicorn[eq]:true
```
Returns: `{ data: [{ total: 52341, unicorns: 1287, unicorn_funding: 3400000000000 }], query_info: { source: "companies", metrics: [...] } }` — note that `data` is a single-element array even for the flat (no-group_by) variant, for shape consistency with the grouped response.



## OpenAPI

````yaml /mintlify/openapi.yaml get /api/analytics/aggregate/{source}/multi-metric
openapi: 3.1.0
info:
  title: Dealroom API
  version: '2026-07-06'
  description: >-
    REST API for the Dealroom platform — companies, funds, founders, investors,
    funding rounds, valuations, taxonomy, news, and aggregate analytics across
    all of them. Authentication uses Auth0 (Bearer JWT or OAuth2
    client_credentials). All endpoints are versioned via the `API-Version`
    header (Stripe-style date-based versioning).
  contact:
    name: Dealroom API support
    email: support@dealroom.co
    url: https://dealroom.co
  termsOfService: https://dealroom.co/terms
  license:
    name: Proprietary — Dealroom commercial license
    url: https://dealroom.co/terms
servers:
  - url: https://api-next.dealroom.co
    description: Production
  - url: https://api-next.beta.dealroom.co
    description: Beta
  - url: https://api-next.staging.dealroom.dev
    description: Staging
security:
  - bearerAuth: []
  - oauth2: []
tags:
  - name: Discovery
    description: API root discovery and functional namespaces.
  - name: Entities
    description: >-
      Companies, investors, people, universities, and other organisations.
      Filter, sort, and paginate the unified entity index. The term `investor`
      refers to the investment firm; `fund` refers to the capital vehicle it
      raises.
  - name: Companies
    description: >-
      Company profiles — the `organization_subtype = company` subset of entities
      (excludes investors, universities, and gov/NGOs). Same response shape as
      the entity index, scoped to companies.
  - name: Universities
    description: >-
      University profiles — the `organization_subtype = university` subset of
      entities. The `university` sub-object carries alumni metrics.
  - name: Government & NGO
    description: >-
      Government bodies and NGOs — the `organization_subtype = gov_ngo` subset
      of entities.
  - name: Transactions
    description: >-
      Funding rounds, equity events, debt, grants, exits, and other
      company-level financial events.
  - name: Valuations
    description: Company valuation history by year and month.
  - name: Investors
    description: >-
      Investor profiles (VCs, corporates, angels, family offices, governments).
      Subset of entities where `is_investor = true`. An investor is the firm
      that makes investments; the capital vehicles it raises are funds available
      via `/investors/{id}/funds`.
  - name: Funds
    description: >-
      Funds — the capital vehicles investor firms raise (e.g. "Fund III", $200M,
      2024). Browse/filter by manager, type, size, and vintage; each fund links
      to its manager (GP). Fund size (`amount`) converts to the requested
      `?currency=` (default USD); `amount_source` carries the original
      native-currency amount.
  - name: People
    description: >-
      Person profiles (founders, executives, angels, and others). Subset of
      entities where `entity_type = 'person'`. Same response shape as founders,
      with company associations, education, and backgrounds.
  - name: Founders
    description: >-
      Founder profiles with company associations and education history. Subset
      of entities where `is_founder = true`.
  - name: News
    description: Curated news articles about companies, funds, deals, sectors, and events.
  - name: Jobs
    description: Active job openings posted by companies, with hiring-trend signals.
  - name: Aggregate
    description: >-
      Composable single- and multi-metric aggregations across companies, funding
      rounds, valuations, founders, and investors.
  - name: Funding Analytics
    description: 'Purpose-built analytics: 2D heatmaps, round transitions, capital funnels.'
  - name: Timeseries
    description: Yearly entity metrics (employees, revenue, valuation).
  - name: Matching
    description: >-
      Investor matching tool: ranked investor recommendations for a given deal
      profile.
  - name: Filters
    description: >-
      Filter registry discovery and value lookup. Use `/api/reference/filters`
      to discover available filters per scope and
      `/api/reference/filters/:key/values` to look up valid values.
  - name: Account
    description: User profile, authentication introspection, and account settings.
  - name: API Keys
    description: >-
      Self-service API key management. Programmatic (M2M) keys for server-side
      and Application (PKCE) keys for browser SPAs.
  - name: Teams
    description: Team membership and invitation management.
  - name: Usage
    description: Request-count usage analytics per API key for billing and introspection.
  - name: Metrics
    description: >-
      Service observability metrics (OpenTelemetry configuration and runtime
      counters).
  - name: Health
    description: Liveness probe (public, unauthenticated).
  - name: Search
    description: >-
      Cross-resource fuzzy search across companies, investors, people,
      universities, and government & NGO bodies.
  - name: Ecosystems
    description: >-
      Curated entity collections that can be filtered, navigated, and compared.
      Includes nested landscape resources.
  - name: Landscapes
    description: Saved entity lists within an ecosystem (e.g. "top fintech in NL").
  - name: Enhancement Requests
    description: User-submitted profile data corrections routed to Dealroom Data Support.
paths:
  /api/analytics/aggregate/{source}/multi-metric:
    get:
      tags:
        - Aggregate
      summary: Multi-metric aggregate
      description: >-
        Return multiple labeled metrics from a single SQL query, each with
        optional per-metric

        filters using aggregate FILTER (WHERE ...) clauses. Supports all metric
        types (COUNT, SUM,

        AVG, MEDIAN, MAX) and optional dimensional grouping (group_by).


        **Metric param format:** `metric=<label>,<metric_type>`

        - First segment = label (lowercase alphanumeric + underscore)

        - Second segment = metric type (e.g., `count`, `sum:total_funding`,
        `percentage:label_a/label_b`)


        **Percentage metrics** (`percentage:numerator/denominator`): Computes
        `ROUND(numerator * 100.0 / NULLIF(denominator, 0), 2)`.

        - Both referenced labels must be defined as non-percentage metrics in
        the same request.

        - Percentage metrics cannot have per-metric filters (apply filters to
        the referenced metrics instead).

        - Example:
        `metric=filtered,count&metric=total,count&metric=pct,percentage:filtered/total`


        **Per-metric filters** (`metric_filter` param):
        `metric_filter=<label>:<filter_expression>`

        - Uses the same AST filter syntax as the shared `filter` param

        - Example: `metric_filter=unicorns:is_unicorn[eq]:true`

        - Compound:
        `metric_filter=funded:and(total_funding[gte]:100000,is_vc_backed[eq]:true)`


        **group_by** (optional): Dimension(s) to group by, comma-separated.

        **sort** (optional): Sort by metric label or `dimension`. Prefix `-` for
        descending (default).

        **limit** (optional): Max results when grouped (1-500, default 25).


        **Post-aggregation filter** (`metric_having` param): Filter grouped rows
        by metric values.

        - Format: `metric_having=<label>[op]:<value>` where op is gt, gte, lt,
        lte, eq, neq

        - Repeatable for multiple conditions (AND semantics)

        - Only valid when `group_by` is present

        - Example:
        `metric_having=percentage[gt]:25&metric_having=filtered[gte]:5`


        **Shared filters** (`filter` param): Uses structured AST syntax, same as
        `/api/analytics/aggregate/:source`.

        - Single filter: `filter=tag_id[eq]:42`

        - AND: `filter=and(tag_id[eq]:42,launch_year[gte]:2020)`

        - OR: `filter=or(hq_location[eq]:133,hq_location[eq]:75)`


        **Example — mixed metrics with group_by:**

        ```

        GET /api/analytics/aggregate/companies/multi-metric
          ?metric=total,count
          &metric=unicorns,count
          &metric=unicorn_funding,sum:total_funding
          &metric_filter=unicorns:is_unicorn[eq]:true
          &metric_filter=unicorn_funding:is_unicorn[eq]:true
          &group_by=hq_country
          &sort=-total
          &limit=10
          &filter=launch_year[gte]:2015
        ```


        **Example — flat (no group_by):**

        ```

        GET /api/analytics/aggregate/companies/multi-metric
          ?metric=total,count
          &metric=unicorns,count
          &metric=unicorn_funding,sum:total_funding
          &metric_filter=unicorns:is_unicorn[eq]:true
          &metric_filter=unicorn_funding:is_unicorn[eq]:true
        ```

        Returns: `{ data: [{ total: 52341, unicorns: 1287, unicorn_funding:
        3400000000000 }], query_info: { source: "companies", metrics: [...] } }`
        — note that `data` is a single-element array even for the flat
        (no-group_by) variant, for shape consistency with the grouped response.
      operationId: multiMetric
      parameters:
        - schema:
            type: string
            enum:
              - founders
              - investors
              - companies
              - funding-rounds
              - valuations
              - entities
              - fundings
            description: The source to aggregate
            example: companies
          required: true
          name: source
          in: path
        - schema:
            type: string
            description: >-
              ISO 4217 currency code for monetary metric conversion. Defaults to
              USD.
            example: EUR
          required: false
          name: currency
          in: query
        - schema:
            anyOf:
              - type: string
                minLength: 1
              - type: array
                items:
                  type: string
                  minLength: 1
                minItems: 1
            description: >-
              Metric definition: label,metric_type. Repeat for multiple metrics.
              Types: count, count_distinct:field, sum:field, avg:field,
              median:field, p25:field, p75:field,
              percentage:numerator_label/denominator_label. Example:
              metric=total,count&metric=unicorns,count&metric=pct,percentage:unicorns/total
            example: total,count
          required: true
          name: metric
          in: query
          example: total,count
        - schema:
            anyOf:
              - type: string
                minLength: 1
              - type: array
                items:
                  type: string
                  minLength: 1
                minItems: 1
            description: >-
              Per-metric filter expression: <label>:<filter_expression>.
              Example: metric_filter=unicorns:is_unicorn[eq]:true
            example: unicorns:is_unicorn[eq]:true
          required: false
          name: metric_filter
          in: query
        - schema:
            anyOf:
              - type: string
                minLength: 1
              - type: array
                items:
                  type: string
                  minLength: 1
                minItems: 1
            description: >-
              Post-aggregation filter: <label>[op]:<value>. Operators: gt, gte,
              lt, lte, eq, neq. Only valid with group_by. Example:
              metric_having=percentage[gt]:25
            example: percentage[gt]:25
          required: false
          name: metric_having
          in: query
        - schema:
            type: string
            minLength: 1
            pattern: ^[a-z][a-z0-9_.]*(?:,[a-z][a-z0-9_.]*)*$
            description: >-
              Dimension(s) to group by, comma-separated. Omit for flat
              aggregation
            example: hq_country
          required: false
          name: group_by
          in: query
          example: hq_country
        - schema:
            type: string
            description: >-
              Filter expression: and(key[op]:value,...), or(...). Example:
              and(tag_id[eq]:42,launch_year[gte]:2020)
            example: and(tag_id[eq]:42,launch_year[gte]:2020)
          required: false
          name: filter
          in: query
        - schema:
            type: string
            pattern: ^-?[a-z][a-z0-9_]*$
            description: Sort by metric label or 'dimension'. Prefix with - for descending
            example: '-total'
          required: false
          name: sort
          in: query
          example: '-total'
        - schema:
            type: string
            description: Number of results to return (1-500, default 25)
            example: '25'
          required: false
          name: limit
          in: query
          example: '25'
      responses:
        '200':
          description: Multi-metric results (grouped or flat depending on group_by)
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/MultiMetricGroupedResponse'
                  - $ref: '#/components/schemas/MultiMetricFlatResponse'
        '401':
          description: >-
            Authentication required. The `Authorization` header was missing, the
            bearer token was malformed, or the token failed signature / expiry
            validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Authentication succeeded but the caller's token does not include the
            permission required for this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - oauth2:
            - read:aggregate
        - bearerAuth:
            - read:aggregate
components:
  schemas:
    MultiMetricGroupedResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties:
              anyOf:
                - type: string
                - type: number
                - type: 'null'
        query_info:
          type: object
          properties:
            source:
              type: string
            group_by:
              type: string
            metrics:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                  type:
                    type: string
                required:
                  - label
                  - type
            total_groups:
              type: number
          required:
            - source
            - group_by
            - metrics
            - total_groups
        currency:
          type: string
      required:
        - data
        - query_info
        - currency
    MultiMetricFlatResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties:
              type: number
        query_info:
          type: object
          properties:
            source:
              type: string
            metrics:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                  type:
                    type: string
                required:
                  - label
                  - type
          required:
            - source
            - metrics
        currency:
          type: string
      required:
        - data
        - query_info
        - currency
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              anyOf:
                - type: array
                  items:
                    type: object
                    properties:
                      path:
                        type: string
                      message:
                        type: string
                    required:
                      - path
                      - message
                - type: object
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                      - type: boolean
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Auth0 JWT access token. Paste a token obtained from your preferred
        OAuth2 flow. For machine-to-machine use, the OAuth2 client_credentials
        scheme below can mint a token directly from your `client_id` /
        `client_secret` inside the Swagger UI Authorize dialog.
    oauth2:
      type: oauth2
      description: >-
        OAuth2 client-credentials flow against the Dealroom Auth0 tenant. Use
        the `client_id` / `client_secret` from a Programmatic API key. Tokens
        are valid for 24h — Swagger UI will reuse the same token across
        operations.
      flows:
        clientCredentials:
          tokenUrl: https://accounts.dealroom.co/oauth/token
          scopes:
            read:entities: Grant the read:entities permission
            read:transactions: Grant the read:transactions permission
            read:valuations: Grant the read:valuations permission
            read:investors: Grant the read:investors permission
            read:founders: Grant the read:founders permission
            read:dimensions: Grant the read:dimensions permission
            read:timeseries: Grant the read:timeseries permission
            read:aggregate: Grant the read:aggregate permission
            read:funding-analytics: Grant the read:funding-analytics permission
            read:ecosystems: Grant the read:ecosystems permission
            write:ecosystems: Grant the write:ecosystems permission
            delete:ecosystems: Grant the delete:ecosystems permission
            write:landscapes: Grant the write:landscapes permission
            delete:landscapes: Grant the delete:landscapes permission
            read:metrics: Grant the read:metrics permission
            create:api-keys: Grant the create:api-keys permission
            read:api-keys: Grant the read:api-keys permission
            delete:api-keys: Grant the delete:api-keys permission
            admin:api-keys: Grant the admin:api-keys permission
            read:usage: Grant the read:usage permission
            read:news: Grant the read:news permission
            read:jobs: Grant the read:jobs permission
            read:people: Grant the read:people permission
            read:teams: Grant the read:teams permission
            write:teams: Grant the write:teams permission
            delete:teams: Grant the delete:teams permission
            manage:team-members: Grant the manage:team-members permission
            read:search: Grant the read:search permission
            write:ai-features: Grant the write:ai-features permission

````