Pagination

Two parameters

Every list takes the same two query parameters, declared once in the spec and shared by every operation. Anything outside the bounds is a 400 with INVALID_PARAMETER; an unknown parameter is ignored, not refused.

per_page tops out at 100 almost everywhere. A larger ceiling (1000, 500, 50) applies to the bulk lists: /v1/firearms/media, /v1/contract/findings, /v1/data/tasks, /v1/updates.

6 operations are rankings rather than lists: they take a single limit, return the top rows and carry no pagination object: /v1/firearms/top, /v1/popular/firearms, /v1/stats/calibers/popular, /v1/stats/manufacturers/prolific, /v1/stats/feature-frequency, /v1/docs/guides/search.

The envelope

A paged response wraps the page in the same object every time. The sample below is built from the schema's own examples, so it cannot drift from what the API sends.

1{2  "success": true,3  "data": [4    /* one page of records */5  ],6  "pagination": {7    "page": 1,8    "per_page": 20,9    "limit": 20,10    "total": 42,11    "totalPages": 312  }13}

• pagination.pageintegerrequired

  The page this response is, 1-based.

• pagination.per_pageintegerrequired

  Page size. Same value as limit.

• pagination.limitintegerrequired

  Page size. Alias of per_page.

• pagination.totalintegeroptional

  Total records matching the query across every page.

• pagination.totalPagesintegeroptional

  How many pages the result set spans at the current per_page.

Page-size is reported under both per_page (matching the request parameter) and limit (retained for existing integrations). They always carry the same value. total and totalPages are omitted for Explorer and anonymous callers.

Walking a list

The loop that works on every plan drives itself from the page it just received, not from totalPages. Four rules and the code in three languages.

flowchart LR
  first["GET the list<br/>with the largest per_page"] --> rows["Read data[]"]
  rows --> short{"Fewer rows<br/>than per_page?"}
  short -->|"yes"| done["That was the last page"]:::ok
  short -->|"no"| deeper{"Next page within<br/>your plan's depth?"}
  deeper -->|"yes"| nextPage["GET page + 1"]
  nextPage --> rows
  deeper -->|"no"| refuse["Refused: 403 PAGINATION_DEPTH_EXCEEDED<br/>filter the list, or upgrade"]:::fail
  totals["total / totalPages"] -.->|"absent on some plans"| trap["Never loop on these"]:::fail

1. 1Stop when a page comes back short. Fewer rows than per_page means it was the last page, on every plan.
2. 2Treat total and totalPages as optional extras. They are absent on Explorer and anonymous calls, so a loop that tests page < totalPages stops after one page there.
3. 3Ask for the largest page you can use. per_page=100 is 100× fewer requests against your per-minute limit and your daily allowance, and reaches the same rows.
4. 4Walk once, then stay current by other means. Each page carries an ETag and answers 304 when unchanged, and data webhooks push catalog changes so a mirror never re-walks the list. More than 10 sequential pages inside 90 seconds is refused.

1# Page 1, then keep going while a page comes back full2curl -H "X-API-Key: your_api_key" \3  "https://api.gunspec.io/v1/firearms?category=rifle&per_page=100&page=1"4 5curl -H "X-API-Key: your_api_key" \6  "https://api.gunspec.io/v1/firearms?category=rifle&per_page=100&page=2"

What each plan may read

Paging is where the plans differ most, and each rule below is enforced by the API rather than by convention. The figures come from the same configuration the middleware reads.

How a refused page request reads

• 403PAGINATION_DEPTH_EXCEEDED

  The plan does not page this deep into a list. Narrow the list with filters, or upgrade for deeper paging.

• 429PAGINATION_BURST

  Too many sequential pages in a short time. Slow the walk down, or use a larger per_page.

Compare the plansEvery catalog protection

Sorting

Where a list can be ordered it declares a sort vocabulary and an order direction; the default order is the one the reference shows for each. Every other list has a fixed order the operation's description states.

• /v1/firearms
  • name
  • weight
  • year
  • caliber
  • created_at
  • favorites

  order: asc | desc

• /v1/me/support
  • created_at
  • updated_at
  • status
  • priority

  order: asc | desc

Every operation that pages

41 operations take page and per_page and answer with the envelope; 6 take a single limit. Each row links to its reference page.

SDKs and agents

The official SDKs expose an auto-paging iterator that applies every rule on this page: it fetches pages on demand, stops on a short page and never reads totalPages.

1for await (const firearm of client.firearms.listAutoPaging({ category: 'rifle' })) {2  console.log(firearm.name); // pages are fetched on demand3}

1for firearm in client.firearms.list_auto_paging({"category": "rifle"}):2    print(firearm["name"])  # pages are fetched on demand

SDK referenceDocs for AI agentsllms.txt

Handing this to a coding agent? The agent packs and llms.txt carry the same rules in a form a model can act on: page from the short-page signal, cap per_page, and read error.reason on a 403 or 429 before retrying.