Pagination, filtering & sorting

All list endpoints - batch results, crawler results, files, webhook deliveries, jobs - share one convention.

Pagination parameters

Query param	Meaning	Default	Range
page	One-based page number	1	≥ 1
per_page	Items per page	endpoint-specific (usually 15)	1 – 100

curl "https://api.scrapeit.io/api/v1/scrape/batch/web/BATCH_JOB_ID/results?page=2&per_page=50" \
  -H "x-api-key: YOUR_SCRAPEIT_API_KEY"

Every paginated response carries the totals in meta:

{
  "data": ["…50 items…"],
  "meta": { "total": 1240, "page": 2, "per_page": 50, "last_page": 25 }
}

Iterate until page === meta.last_page (or until data comes back empty).

Large lists (jobs, files, activity, webhook deliveries) count at most 10,000 rows ahead (or up to the page you are on, when it is deeper) and serve pages up to 1,000. When more rows match, meta.total_is_capped is true: total and last_page are then a lower bound (the dashboard shows 10,000+), and last_page is always past the current page, so the loop above keeps going. Narrow the list with filters or a date range to reach older rows.

Sorting

Pass sort with comma-separated field names; prefix a field with - for descending order:

?sort=-createdAt            newest first
?sort=status,-createdAt     by status, then newest first

• Up to 5 sort fields per request.
• Each endpoint allows only its documented public field names (an allowlist - unknown fields are ignored, so a typo silently falls back to the default order).
• When no valid sort is supplied, endpoints use a stable default, usually -createdAt.
• The request log (GET /api/v1/jobs, tab api_requests) sorts by status, credits or product, and the activity log by action, entityType, result or userId, within 7 days unless you pass date_from: the 7 days before date_to when you pass only date_to, otherwise the last 7 days. Sort by -createdAt (the default) to page through the whole history.

Filtering

List endpoints accept endpoint-specific filter params documented in the OpenAPI reference - for example webhook deliveries filter by delivery status, and jobs filter by status, search and date_from/date_to. Filters combine with pagination and sorting freely.

Related pages

• Requests & responses - the { data, meta } envelope.
• Batch Scraping and Website Crawler - paginated results in practice.