Pagination

List responses in RolesAPI paginate with limit and offset query parameters and describe their position in the meta block of the envelope. The two endpoints you will page most are GET /v1/jobs/{id}/results and GET /v1/usage; GET /v1/jobs pages the same way.

What is in the meta block?

{
  "data": [ { "job_key": "a1b2c3d4e5f60718", "title": "Senior Backend Engineer" } ],
  "meta": {
    "total": 412,
    "count": 100,
    "limit": 100,
    "offset": 0,
    "has_more": true
  },
  "request_id": "req_7c2f90de"
}

Field	Meaning
total	Total items matching the request, across all pages.
count	Items in data on this page.
limit	The page size you asked for (or the default).
offset	How many items were skipped before this page.
has_more	true if offset + count < total — there is at least one more page.

How do I fetch every page?

Loop until has_more is false, advancing offset by count each time.

With curl and jq:

OFFSET=0
while : ; do
  PAGE=$(curl -s "https://api.rolesapi.com/v1/jobs/job_01hxyz/results?limit=100&offset=$OFFSET" \
    -H "Authorization: Bearer rk_live_your_key")
  echo "$PAGE" | jq -c '.data[]'
  HAS_MORE=$(echo "$PAGE" | jq '.meta.has_more')
  [ "$HAS_MORE" = "true" ] || break
  OFFSET=$((OFFSET + $(echo "$PAGE" | jq '.meta.count')))
done

With Python and httpx:

import httpx

BASE = "https://api.rolesapi.com"
HEADERS = {"Authorization": "Bearer rk_live_your_key"}

def all_results(job_id: str, limit: int = 100):
    offset = 0
    while True:
        r = httpx.get(
            f"{BASE}/v1/jobs/{job_id}/results",
            params={"limit": limit, "offset": offset},
            headers=HEADERS,
        )
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        if not body["meta"]["has_more"]:
            break
        offset += body["meta"]["count"]

for role in all_results("job_01hxyz"):
    print(role["title"], "-", role["company"]["name"])

Anything else to know?

• Each page request is one API call against your rate limit, but paging through results consumes no additional credits — you paid when the job processed the roles.
• Advance by meta.count, not by limit — the last page is usually short.
• If you want the whole result set in one artifact instead of pages, request ?format=csv or ?format=ndjson on the results endpoint. See Output formats.
• GET /v1/usage supports since (ISO 8601 timestamp) alongside limit to bound the window before paging. See Account.