Aggregate companies

syrto_aggregate_companies returns statistical summaries (count, average, median, min, max) for companies matching your filters. Use it to understand market segments - e.g. “average revenue of medium manufacturing companies in Veneto” or “how many large companies are in sector C”.

This tool returns aggregate statistics, not individual company data. To find specific companies matching the same filters, use syrto_search_companies.

Use this tool to

Count companies matching a set of criteria
Get average, median, or range statistics for a metric across a segment
Benchmark a company against its market segment
Break one population down by sector, area or size band in a single call
Get portfolio statistics over an explicit list of companies

Arguments

integer

required

Fiscal year to aggregate.

string[]

required

1-10 metric slugs to compute statistics for. Use syrto_search_metric_definitions or syrto_list_available_metrics to find valid slugs.Example: ["revenues_from_sales_and_services", "ebitda"]

object

A single structured filter object narrowing which companies are aggregated. It takes exactly the same sections as syrto_search_companies: company_ids, anagraphic, state_aids, people, financial, and radar. Omit it to aggregate over every company for the year.All set filters combine with AND, both within a section and across sections. See Search companies for each section’s fields, or fetch the catalog at runtime with syrto_get_search_filter_docs.The location filters nuts, lau and country_code count companies by their registered headquarters. To count them by where they have a registered branch instead, use anagraphic.has_branch_in.An invalid filters object returns an error naming the bad field.

string[]

Break the aggregate down by these keys instead of returning one figure for the whole filter set - one aggregate per group, in one call. Give 1 to 3 keys, each named once; two keys is a cross-tab, so ["nace_section", "nuts1"] is sector by macro-region.

Key	Groups by
`nace_section`	NACE section, the 21 top-level letters A-U
`nace_division`	NACE division, 2 digits
`nace_group`	NACE group, 3 digits
`nace_class`	NACE class, 4 digits - the finest sector level
`nuts1`	NUTS 1 macro-region
`nuts2`	NUTS 2 region
`nuts3`	NUTS 3 province
`lau`	Municipality (comune)
`locality`	Town name as filed in the address
`postal_code`	Postal code (CAP)
`country_code`	Country of the registered address
`size`	Size band XS / S / M / L

filters and group_by compose: filter to the population you care about, then group it along the axis you want it split by. At most 200 groups come back, largest first, with the true total in the response - fewer than that when 200 groups would not fit one response. A combination with too many distinct groups is refused; coarsen a key or narrow the population.

string[]

Additional statistics on top of the count / average / median / min / max every response carries. Omit for the compact default.

Value	Adds
`percentiles`	`p10` and `p90` - the range the middle 80% of the population sits in, which is what a “typical range” question wants and what min/max cannot answer, since one outlier sets each
`dispersion`	`std_dev`, the population standard deviation
`sum`	A total, and only for metrics a total makes sense for

sum comes back null for a percentage, a rate, a day count, an adimensional ratio or a radar score, with the metrics named in warning. Asking for anything here also adds each metric’s uom (unit of measure). It costs response size, which under group_by means fewer groups fit - ask for what you will read.

string

"en" for English (default) or "it" for Italian.

Returns

object[]

One entry per requested year, each containing:

integer

Total number of companies matching the filters.This is not the count inside employee_stats or metric_stats: those say how many of these companies have a value for that particular field, so a metric only half the population reports has a much smaller one. Divide by whichever is the right denominator for the question.

object

Employee count statistics across matching companies:

count - number of companies with employee data
average, median, minimum, maximum - statistical summaries

object[]

One entry per requested metric slug, each with:

name - human-readable metric name (use this for display, not slug)
slug - internal identifier
stats.count - number of companies with data for this metric
stats.average, stats.median, stats.minimum, stats.maximum - statistical summaries
uom - unit of measure, null when the metric is adimensional (a ratio, index or radar score). Present only when extra_stats was used

With extra_stats, each stats block also carries the subset you asked for: p10 / p90, std_dev, and sum. A statistic you did not ask for is absent; sum present but null means it was asked for and withheld as meaningless for that metric.

object

Radar score statistics across matching companies:

efficiency_avg, efficiency_median - Efficiency score summaries (0–100)
size_avg, size_median - Size score summaries (0–100)

integer

Only with a company_ids filter, and beside the years list rather than inside each year entry: the number of IDs supplied, to compare against each year’s company_count.It detects row loss only. A shortfall means some IDs matched no row for the year, or failed the other supplied criteria - the API cannot say which.

Each ID in a company_ids filter names one statement. A list containing both the individual and the consolidated ID of the same company double-counts it in every statistic, and the counts cannot detect that. Keep an aggregated list on one basis.

With `group_by`

The same per-year statistics arrive once per group instead of once for the whole population, and the response carries these in place of years:

string[]

The keys the breakdown used, echoed back.

integer

How many groups the population has. Compare it with the length of groups, which is capped at the largest 200 and by response size below that - so a rich extra_stats selection can itself be why fewer groups came back. warning says so, and names the cheapest lever.

object[]

Each with key - one entry per requested key, its value null when the companies in that group have no value for it, such as no NACE code - and its own years list.

company_ids_requested is carried on this shape too, beside groups. The groups’ company_count values summing to less than it is the breakdown’s row-loss signal.

Precision

count, sum, average, minimum and maximum are exact at any population size. Above roughly 8,000 contributing values, p10, p90 and median are sample estimates that move a few percent between identical calls - quote them rounded. warning says when this applies. Beside result, the response carries the fields every tool returns. On this tool display_title is always Syrto AI and subtitle is not set.

Example

Average revenue for large manufacturers in Emilia-Romagna:

{
  "year": 2023,
  "aggregate_metric_slugs": ["revenues_from_sales_and_services"],
  "filters": {
    "anagraphic": { "nace": ["C"], "nuts": ["ITH5"] },
    "financial": { "size": ["L"] }
  }
}

Response (abbreviated):

{
  "result": {
    "years": [
      {
        "year": 2023,
        "company_count": 3690,
        "employee_stats": {
          "count": 3045,
          "average": 333.15,
          "median": 201.0
        },
        "metric_stats": [
          {
            "name": "Revenues From Sales And Services",
            "slug": "revenues_from_sales_and_services",
            "stats": {
              "count": 3690,
              "average": 214504329.44,
              "median": 88501574.0
            }
          }
        ],
        "radar": {
          "efficiency_avg": 61.54,
          "efficiency_median": 68.25,
          "size_avg": 80.45,
          "size_median": 80.42
        }
      }
    ]
  },
  "reference_url": "https://app.syrto.ai",
  "display_title": "Syrto AI",
  "allowance": "▕████████████████░░░░▏"
}

Which sector by macro-region cells are thin, in one call:

{
  "year": 2023,
  "aggregate_metric_slugs": ["revenues_from_sales_and_services"],
  "group_by": ["nace_section", "nuts1"],
  "filters": { "financial": { "size": ["M", "L"] } }
}

Portfolio statistics over a list you already hold, with a typical range:

{
  "year": 2023,
  "aggregate_metric_slugs": ["ebitda", "roe"],
  "filters": { "company_ids": ["<id1>", "<id2>", "<id3>"] },
  "extra_stats": ["percentiles"]
}

Getting started

Tools

Aggregate companies

Use this tool to

Arguments

Returns

With `group_by`

Precision

Example

​Use this tool to

​Arguments

​Returns

​With group_by

​Precision

​Example

Use this tool to

Arguments

Returns

With `group_by`

Precision

Example