---
title: "Expected alert volume over the last 90 days, and what needs action today."
method: POST
path: "/surveillance/preview"
tags: ["surveillance"]
---

# Expected alert volume over the last 90 days, and what needs action today.

`POST /surveillance/preview`

## Request

- Base URL: `https://api.ismalicious.com`
- URL: `https://api.ismalicious.com/surveillance/preview`
- Auth: one of:
  - API key in header `X-API-KEY`
  - HTTP bearer
  - HTTP basic

120 previews per hour per organisation.

## Request body

- PreviewRequest
  - `components` ComponentInput[], required
    - `cpe` string, nullable
    - `cpeProduct` string, nullable
    - `cpeVendor` string, nullable
    - `dependencyScope` 'Direct' | 'Transitive' | 'Dev' | 'NotApplicable': `WatchComponent.dependencyScope`.
    - `ecosystem` string, nullable
    - `identityKey` string, nullable
    - `monitored` boolean, nullable
    - `name` string, nullable
    - `packageName` string, nullable
    - `purl` string, nullable
    - `version` string, nullable
    - `versionBranch` string, nullable
  - `windowDays` integer, nullable: 7–90, default 90.

## Response `200`

OK

- PreviewResponse
  - `expected` ExpectedVolume, required
    - `daily` integer, required
    - `discarded` integer, required
    - `immediate` integer, required
    - `weekly` integer, required
  - `notices` SourceNotice[], required: Notices the terms of a source behind any verdict of the preview (its counts included) require to be shown with it: VulnCheck's (§12). Empty when none contributed.
    - `matchSource` 'NvdCpe' | 'Osv' | 'Csaf' | 'VulnCheck' | 'OpenCve' | 'Legacy' | 'Cna', required: `ExposureFindingComponent.matchSources` entries.
    - `name` string, required: `VulnCheck`.
    - `source` string, required: The source's id in the attribution manifest (`GET /cve/attribution`): `vulncheck`.
    - `termsUrl` string, nullable: The terms that require the notice.
    - `text` string, required: Shown as is: « This product uses data from VulnCheck (https://vulncheck.com). »
    - `url` string, required: The publisher's site.
  - `today` TodayItem[], required
    - `commonName` string, nullable
    - `componentName` string, required
    - `cveId` string, required
    - `matchSources` MatchSource[], required: The sources of the ranges behind the verdict (`VULNCHECK` among them when VulnCheck's ranges contributed).
    - `observedVersion` string, nullable
    - `priority` 'P1' | 'P2' | 'P3', required: `ExposureFinding.priority`: P1 immediate, P2 daily digest, P3 weekly (default cadences; the organisation's policy can change them).
    - `proof` 'Exploited' | 'Kev' | 'Likely' | 'Unverified' | 'Low', required: `ExposureFinding.proof` — the Exposure group, in display order.
    - `title` string, nullable
    - `versionState` 'Affected' | 'Unverified' | 'NotAffected' | 'Fixed', required: `ExposureFinding.versionState` / `ExposureFindingComponent.versionState`.
  - `windowDays` integer, required

## Other responses

- `400`: Invalid request
- `401`: Unauthorized
- `429`: 120 previews per hour per organisation
- `503`: The limiter is unavailable

## Changes

- **2026-11-01** `e802f56e895a`: 2 info
  - added the required property `notices` to the response with the `200` status
  - added the required property `today/items/matchSources` to the response with the `200` status
- **2026-10-23** `7c8ce9039cf7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ismalicious/apis/ismalicious-threat-intelligence-api/changes/surveillance/preview/post.md)

---

[API](https://skmtc.dev/ismalicious/apis/ismalicious-threat-intelligence-api.md) - [All operations](https://skmtc.dev/ismalicious/apis/ismalicious-threat-intelligence-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ismalicious/apis/ismalicious-threat-intelligence-api/revisions/b6f45e6169a7?raw)