Skip to main content
List endpoints in the Hacktron REST API share a consistent set of query parameters for pagination, sorting, and filtering.

​
Pagination

Most list endpoints use page‑based pagination:
ParameterTypeDefaultMaxDescription
pageinteger1—1‑based page number.
limitinteger15100Number of items per page.
The response echoes the current page and limit, and includes total for building pagination controls or iterating until exhausted: 
{
  "data": [/* items for this page */],
  "total": 284,
  "page": 2,
  "limit": 50
}
To iterate all pages: 
page=1
while : ; do
  curl -s "https://api.hacktron.ai/v1/findings?page=$page&limit=100" \
    -H "X-Api-Key: $HACKTRON_API_KEY"
  # ... extract data, break when (page * limit) >= total
  page=$((page + 1))
done
Cost Estimations use offset‑based pagination instead, with limit (default 50, max 100) and offset (default 0). This is called out explicitly on the List Cost Estimations page.

​
Sorting

Endpoints that support sorting accept two parameters:
ParameterTypeDescription
sort_byenumWhich field to sort by. Valid values vary per endpoint.
sort_orderenumASC or DESC. Defaults to DESC.
The allowed sort_by values are documented on each list endpoint. Examples:
  • List scans: created_at, updated_at, status
  • List findings: found_at, updated_at, severity
If sort_by is omitted, the endpoint-specific default applies (see each list page).

​
Filtering

Filters are passed as additional query parameters. Each list endpoint documents the filters it supports. The patterns below are shared across list endpoints.

​
Enum filters

Enum filters accept the canonical lower‑snake‑case value and return only records that match: 
# Only critical findings
GET /findings?severity=critical

# Only scans that have finished successfully
GET /scans?status=completed

​
Scoped filters

Some filters restrict results to a related resource: 
# Findings for a specific scan
GET /findings?scan_id=123e4567-e89b-12d3-a456-426614174000
Scoped filters validate that the target resource belongs to your organization. 404 is returned if the resource does not exist or is not visible to the key.

​
Combining filters

Multiple filters combine with AND semantics: 
GET /findings?severity=high&state=open&scan_id=...
There is no OR operator. Call the endpoint multiple times and merge results client-side if a union is required.

​
Example

Fetch the 25 most recently updated high‑severity findings that are still open: 
curl "https://api.hacktron.ai/v1/findings?severity=high&state=open&sort_by=updated_at&sort_order=DESC&page=1&limit=25" \
  -H "X-Api-Key: $HACKTRON_API_KEY"