GET /v1/statistics/distribution

How CVEs spread across bands: how many at each CVSS score, at each exploitation-probability level, per attack vector, per severity.

Where /v1/statistics/top ranks open-ended values (thousands of CWEs or vendors), this route splits the population into a small set of closed, ordered bands.

Required scope: stats-global

Request

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

Query parameters

Parameter	Type	Default	Description
metric	string	cvss	cvss, epss, attack_vector, severity
period	string	—	2026, 2026-Q1, 2026-03, 2026-W12, 2026-03-15
from / to	date	—	Explicit bounds, ignored when period is set

The four metrics

metric	Bands	Use
cvss	0.5-wide bands, 0.0 to 10.0	Technical severity histogram
epss	<1%, 1–10%, 10–30%, 30–60%, >60%	Probability of exploitation within 30 days
attack_vector	Network, Adjacent, Local, Physical, Unknown	Read from the CVSS vector (AV:)
severity	CRITICAL … UNKNOWN	Breakdown by level and PoC coverage

Response 200 OK

{
  "metric": "epss",
  "label": "Probabilité d'exploitation EPSS, en cinq paliers",
  "from": "2026-01-01",
  "to": "2026-12-31",
  "grand_total": 38104,
  "buckets": [
    { "bucket": "<1%",    "total": 30218, "with_poc": 2104, "kev": 3,  "share_pct": 79.30, "poc_pct": 7.0 },
    { "bucket": "1–10%",  "total": 5433,  "with_poc": 1187, "kev": 11, "share_pct": 14.26, "poc_pct": 21.8 },
    { "bucket": "10–30%", "total": 1502,  "with_poc": 611,  "kev": 14, "share_pct": 3.94,  "poc_pct": 40.7 },
    { "bucket": "30–60%", "total": 604,   "with_poc": 341,  "kev": 18, "share_pct": 1.59,  "poc_pct": 56.5 },
    { "bucket": ">60%",   "total": 347,   "with_poc": 264,  "kev": 29, "share_pct": 0.91,  "poc_pct": 76.1 }
  ]
}

Bands come back in logical order, not alphabetical — otherwise 10–30% would sort before 1–10%, and LOW before MEDIUM.

Fields

Field	Type	Description
grand_total	integer	CVEs covered by the metric over the window
bucket	string	Band label
total	integer	CVEs in this band
with_poc	integer	Of which at least one known public PoC
kev	integer	Of which present in the KEV catalog
share_pct	float	Share of the band in grand_total
poc_pct	float	PoC coverage rate within the band

These totals do count CVEs

Each CVE falls into exactly one band, so share_pct adds up to 100 % and grand_total is a CVE count. That is the difference with /v1/statistics/top on the cwe dimension, where a CVE carrying two CWEs counts twice.

grand_total varies between metrics over the same window: only CVEs with a CVSS score enter cvss, with an EPSS score epss, with a vector attack_vector. The severity metric covers everything, severity defaulting to UNKNOWN.

Database totals

GET /api/v1/statistics/totals

No parameters: global counters, across all states.

{
  "total": 312044,
  "published": 297811,
  "rejected": 13402,
  "reserved": 831,
  "kev": 1284,
  "poc": 41209,
  "triple_threat": 218,
  "avg_cvss": 7.02,
  "avg_epss": 2.914
}

Field	Description
rejected reserved	CVEs withdrawn, or reserved without publication
triple_threat	Critical and in the KEV catalog and with a public PoC — the intersection that calls for immediate action
avg_epss	As a percentage, not a probability

The only route that sees unpublished CVEs

Every other statistic covers PUBLISHED only. rejected and reserved are therefore unavailable anywhere else, and this route’s totals will not match the sum of /v1/statistics/timeseries points.

Example

PoC coverage by severity for the current year:

curl -s \
  -H "Authorization: Bearer twa_your_key_here" \
  "https://app.techwatchalert.com/api/v1/statistics/distribution?metric=severity&period=2026" \
  | jq '.buckets | map({severity: .bucket, cves: .total, with_poc, rate: .poc_pct})'