GET /v1/statistics/top

The most represented values on a dimension — which weaknesses, vendors, products and assigning authorities dominate a given period.

The same route serves the all-time ranking and the ranking for one specific week: only the window changes.

Required scope: stats-global

Request

GET /api/v1/statistics/top
Authorization: Bearer twa_your_key_here

Query parameters

Parameter	Type	Default	Description
`dimension`	`string`	`cwe`	`cwe`, `vendor`, `product`, `cna`
`period`	`string`	—	`2026`, `2026-Q1`, `2026-03`, `2026-W12`, `2026-03-15`
`from`	`date`	`1999-01-01`	Start bound, ignored when `period` is set
`to`	`date`	tomorrow	End bound, ignored when `period` is set
`limit`	`integer`	`15`	1 to 100
`sort`	`string`	`total`	`total`, `critical`, `high`, `kev`, `poc`
`kev_only`	`boolean`	`false`	Count only CVEs in the KEV catalog

With neither period nor from/to, the ranking covers the entire history.

The cna dimension exposes the authority that assigned the identifier (CVE Numbering Authority) — useful to see which vendors and bodies publish the most.

Response `200 OK`

{
  "dimension": "cwe",
  "label": "Type de faiblesse (CWE)",
  "period": "2026-W12",
  "from": "2026-03-16",
  "to": "2026-03-22",
  "kev_only": false,
  "sort": "total",
  "grand_total": 1184,
  "distinct_values": 97,
  "items": [
    {
      "rank": 1,
      "value": "CWE-79",
      "label": "CWE-79",
      "total": 213,
      "critical": 4,
      "high": 61,
      "kev": 1,
      "poc": 28,
      "avg_cvss": 6.12,
      "avg_epss": 1.884,
      "share_pct": 17.99
    }
  ]
}

Fields

Field	Type	Description
`grand_total`	`integer`	Sum across the whole dimension, the basis for `share_pct`
`distinct_values`	`integer`	Number of distinct values in the window
`value`	`string`	Grouping key (lowercased for `vendor`, `product`, `cna`)
`label`	`string`	Original form, for display
`share_pct`	`float`	Share of `grand_total`

In kev_only mode, sort=total sorts on the KEV total: the ranking always reflects what is displayed.

Ranking over time

GET /api/v1/statistics/top-trend

Tracks the top N values bucket by bucket, to draw one line per value.

Parameter	Type	Default	Description
`dimension`	`string`	`cwe`	`cwe`, `vendor`, `product`, `cna`
`granularity`	`string`	`year`	`day`, `week`, `month`, `quarter`, `year`
`period` / `from` / `to`	—	—	Same behaviour as above
`limit`	`integer`	`8`	1 to 25

The top is computed once over the whole window, then those same values are tracked in every bucket. This is deliberate: recomputing the top per bucket would make the series change subject from one point to the next, and the chart would become unreadable.

{
  "dimension": "cwe",
  "granularity": "year",
  "from": "2020-01-01",
  "to": "2026-09-11",
  "series": [
    { "value": "CWE-79", "label": "CWE-79", "total": 41203 }
  ],
  "points": [
    { "period": "2020-01-01", "CWE-79": 5120, "CWE-89": 2044 }
  ]
}

Each points object carries one key per tracked value, listed in series. Missing combinations are 0, so the series stay continuous.

Errors

Code	Detail	Cause
`422`	`Dimension inconnue…`	Value outside `cwe`, `vendor`, `product`, `cna`
`422`	`Tri inconnu…`	`sort` outside the allowed list
`422`	`Période « … » non reconnue`	Invalid `period` format

Examples

Top CWEs for one specific week:

curl -s \
  -H "Authorization: Bearer twa_your_key_here" \
  "https://app.techwatchalert.com/api/v1/statistics/top?dimension=cwe&period=2026-W12&limit=10" \
  | jq '.items | map({rank, cwe: .value, total, share: .share_pct})'

Vendors most represented in the KEV catalog, all time:

curl -s \
  -H "Authorization: Bearer twa_your_key_here" \
  "https://app.techwatchalert.com/api/v1/statistics/top?dimension=vendor&kev_only=true&limit=15" \
  | jq '.items | map({vendor: .label, kev: .total})'