---
title: "GET /stats/kev"
method: GET
path: "/stats/kev"
tags: ["stats"]
---

# GET /stats/kev

`GET /stats/kev`

## Request

- Base URL: `/api` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/stats/kev`
- Auth: API key in header `X-API-KEY`

Returns known-exploited inclusion for a source. Without granularity, the membership counts: how many of its records appear in each catalogue. With granularity=year or month, how many each catalogue listed per period, bucketed on the date the catalogue listed the record rather than on the record's publication date.

## Query parameters

- `source` string
- `granularity` '' | 'year' | 'month'
- `period` string

## Response `200`

Success.

- StatsKEV
  - `available` boolean: False when this source does not maintain a known-exploited index.
  - `basis` string: What the counts are counted on: `membership` without granularity (set membership, carrying no date), `listed_at` with it (the date each catalogue listed the record: first_seen_at, then recorded_at, then status_updated_at -- never the record's publication date).
  - `catalogs` object: Catalogue short name -> record count, or -> {period: count} with a granularity. These overlap: a record listed by two catalogues is counted by both, so they sum to more than `exploited` (or than `totals`).
  - `computed_at` string: When the period buckets were last prepared.
  - `exploited` integer: Records appearing in at least one known-exploited catalogue. Null in the period form, where `totals` carries the series.
  - `granularity` string: year or month with a period series, null without one.
  - `period` string: With granularity=month, the year broken into months.
  - `ratio` number: exploited / total, or null when the source is empty.
  - `scope_catalogs` object: The catalogue short names the figure was measured over, present when `scoped`. Its own field because `catalogs` carries the per-catalogue series in the period form.
  - `scoped` boolean: True when the figure is restricted to the catalogues configured for this source (STATS_KEV_CATALOGS): `exploited` is then the union of exactly the catalogues listed in `catalogs`. False when it covers every catalogue the instance knows.
  - `source` string: The source reported on.
  - `total` integer: The denominator: currently-published records, or every record held. Null in the period form.
  - `total_basis` string: Which population ``total`` counts: ``state_published`` for a source whose lifecycle index says what is published now, ``date_published`` for one that only records when a vulnerability was published, ``held`` for one that does neither. Null in the period form.
  - `totals` object: Period -> distinct records that became known exploited in it, each counted once in the period its first catalogue listed it. Only with a granularity.
  - `unattributed` integer: Exploited records held under a catalogue this instance cannot name, counted the same way when `scoped`: a record a scope leaves out is not unattributed, but one in no known catalogue still is. Non-zero means the local catalogue reference data is absent or stale. Null in the period form, where `unattributed_periods` carries the series.
  - `unattributed_periods` object: Period -> exploited records held under a catalogue this instance cannot name. Only with a granularity; the membership form reports the count in `unattributed`.

## Other responses

- `400`: The request could not be satisfied.

## Changes

- **2026-10-09** `aee06988b549`: 2 info
  - added the new optional `query` request parameter `granularity`
  - added the new optional `query` request parameter `period`
- **2026-09-21** `a850f2cbf0bc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vulnerability-lookup/apis/vulnerability-lookup-api/changes/stats/kev/get.md)

---

[API](https://skmtc.dev/vulnerability-lookup/apis/vulnerability-lookup-api.md) - [All operations](https://skmtc.dev/vulnerability-lookup/apis/vulnerability-lookup-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vulnerability-lookup/apis/vulnerability-lookup-api/revisions/b4dedf027493?raw)