Pagination
The VDB API's two pagination styles, limit and offset or page and perPage on the package catalogue, with their defaults, caps and how to walk every page.
limit and offset
Most list routes take limit and offset in the query string and echo them back with the total:
{
"total": 1342,
"limit": 100,
"offset": 200,
"hasMore": true,
"...": "the page of results"
}
hasMore is offset + limit < total. To walk every page, add limit to offset until hasMore is false.
Each route’s default and cap are in the OpenAPI document (GET /v2/spec) and the endpoint reference. Requests are checked against the document, so a limit above the cap, below 1 or not a number, or an offset above 100,000, answers 400 with "field": "limit" (or offset) rather than being adjusted; see Request validation. Leave limit out to get the default.
| Routes | Default limit |
Cap |
|---|---|---|
Product and package routes (/product/*, /{package}/versions, /{package}/vulns, /{ecosystem}/*), /identifiers, /gcve, /eol/products, /eol/identifiers, /vuln/{id}/fixes/*, /vuln/{id}/affected, /vuln/{id}/snort-rules, /vuln/{id}/yara-rules, /iocs |
100 | 500 (100 on /{package}/versions with withVulnIntel=1) |
/snort-rules, /yara-rules, /attack-techniques, /kev, /vex, /triage, /virtual-patches, /countermeasures, /vuln/{id}/virtual-patches, /vuln/{id}/countermeasures |
100 | 200 |
/exploits (search), /packages/search |
100 | 100 |
/exploits/{identifier} |
100 | 1,000 |
/scorecard/search |
20 | 100 |
/search/vulns |
10 | 50, and offset at most 1,000 |
/vulnetix-kev, /ai-discoveries |
1,000 | 5,000 |
The CLI’s list commands use lower defaults of their own (often --limit 50); see the command reference.
page and perPage
The package catalogue routes page by number instead:
| Route | page default |
page cap |
perPage default |
perPage cap |
|---|---|---|---|---|
/packages |
1 | 2,000 | 50 | 50 |
/packages/org |
1 | 2,000 | 50 | 50 |
/packages/enrichment |
1 | 500 | 25 | 100 |
The answer carries a pagination object:
{ "pagination": { "page": 2, "perPage": 50, "totalRows": 812, "totalPages": 17 } }
Fan-out answers
When a purl, CPE, TEI or SWID tag sits in a /v2/vuln/{identifier}/* path, the route runs for at most 50 of the advisories it resolves to and sets hasMore: true if there were more. There is no offset for this; narrow the input instead (add a version, an ecosystem or a vendor). See Identifiers and inputs.
Walking pages with curl
AUTH="Authorization: ApiKey ${VULNESIS_ORG_ID}:${VULNESIS_API_KEY}"
offset=0
while :; do
page=$(curl -s -H "$AUTH" "https://api-vdb.vulnes.is/v2/identifiers/2024/3?limit=500&offset=${offset}")
echo "$page" | jq -r '.identifiers[]'
[ "$(echo "$page" | jq -r '.hasMore')" = "true" ] || break
offset=$((offset + 500))
done
Each page is one request against your daily quota.