Pagination

This page describes REST API pagination in the HostRepute API: the list endpoints return their items in pages, and you ask for the next page with the page parameter.

Parameters

Both are query parameters:

• page is the page to return, a whole number from 1. It defaults to the first page.
• per_page is how many items a page holds, within these limits:

Setting	Default	How to change
Items per page in API lists	15 items	The per_page query parameter
Largest per_page	100 items	Fixed

• A value out of range, such as page=0 or per_page=101, is refused with 422, for example “The per page field must not be greater than 100.” Read errors.
• A page past the last one isn’t an error: it returns 200 with an empty data list.
• The lists take no sort or filter parameters.

Paginated endpoints

Endpoint	Lists	Ability
GET /api/v1/hosts	The domains and IPs your team monitors	host:read
GET /api/v1/data-sources	The blocklists HostRepute can check	data-source:read
GET /api/v1/data-source-groups	Your team’s check profiles	data-source-group:read
GET /api/v1/alerts	Your team’s alert channels	alert:read
GET /api/v1/alert-groups	Your team’s delivery hours	alert-group:read

No other endpoint returns pages. The private agent’s task list, GET /api/v1/certificate-agent/tasks, takes a limit instead (1 to 100, 25 by default): read check internal certificates with a private agent.

Response

A page holds the items in data, plus links and meta. This request asks for 2 items per page from a team with 3 domains and IPs, and shows only links and meta:

Request

curl "https://app.hostrepute.com/api/v1/hosts?per_page=2" \
  -H "Authorization: Bearer $HOSTREPUTE_TOKEN" \
  -H "Accept: application/json" \
  | jq '{links, meta}'

Output

{
  "links": {
    "first": "https://app.hostrepute.com/api/v1/hosts?page=1",
    "last": "https://app.hostrepute.com/api/v1/hosts?page=2",
    "prev": null,
    "next": "https://app.hostrepute.com/api/v1/hosts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://app.hostrepute.com/api/v1/hosts?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": "https://app.hostrepute.com/api/v1/hosts?page=2",
        "label": "2",
        "page": 2,
        "active": false
      },
      {
        "url": "https://app.hostrepute.com/api/v1/hosts?page=2",
        "label": "Next »",
        "page": 2,
        "active": false
      }
    ],
    "path": "https://app.hostrepute.com/api/v1/hosts",
    "per_page": 2,
    "to": 2,
    "total": 3
  }
}

Field	Meaning
links.first, links.last	The URLs of the first and last pages.
links.prev, links.next	The URLs of the previous and next pages, null on the first and last page.
meta.current_page	The page you got.
meta.last_page	The number of the last page. When current_page equals it, you have every item.
meta.per_page	The page size used.
meta.total	How many items the whole list has.
meta.from, meta.to	The positions of the first and last item on this page, counted from 1; null on an empty page.
meta.path	The endpoint’s URL without parameters.
meta.links	One entry per page-number link, for building page navigation: url, label, page and whether it’s active. The first and last entries are the previous and next links, and their labels contain the HTML entities « and ».

The page URLs keep only page

links and meta.links don’t carry per_page, so following links.next after a request with per_page=100 returns 15 items again. Build each request yourself, with the same per_page and the next page number.

Read every page

This loop prints the UUID and address of every domain and IP, 100 at a time, and stops after the last page or on an error:

Terminal

page=1
while :; do
  body=$(curl -sS "https://app.hostrepute.com/api/v1/hosts?per_page=100&page=$page" \
    -H "Authorization: Bearer $HOSTREPUTE_TOKEN" \
    -H "Accept: application/json")
  if ! printf '%s' "$body" | jq -e '.data' > /dev/null; then
    printf '%s\n' "$body" >&2
    break
  fi
  printf '%s' "$body" | jq -r '.data[] | [.uuid, .host] | @tsv'
  [ "$(printf '%s' "$body" | jq '.meta.current_page < .meta.last_page')" = true ] || break
  page=$((page + 1))
done

• Each page is one request against the rate limit of 120 per minute per team, so per_page=100 reads a long list in the fewest requests.
• Pages are counted when you ask for them. If items are added or deleted while you page through a list, an item can show up twice or be missed; read the list again when you need an exact copy.

Related

• Make your first API call reads a first list.
• Errors lists the 422 answers for bad paging values.
• Rate limits explains how many pages you can read per minute.
• API reference documents each list endpoint.