Skip to content

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.

Updated 05 Nov 2026Markdown

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.

esc
↑ ↓ move↵ openSearches in your browser. A key like autonomy.max or a code like threshold_required jumps straight to it.