Skip to main content
All list endpoints in the 8bitedge API return paginated results. Rather than dumping every record in a single response, the API slices results into pages you retrieve sequentially. You can choose between page mode (the default) and cursor mode depending on your use case — page mode is convenient for random access and UI paging, while cursor mode is more efficient for streaming large or frequently-changing datasets without risk of skipping or duplicating records.

​
Common query parameters

Every list endpoint accepts the following query parameters to control pagination:
ParamTypeDefaultNotes
limitint25Page size; capped by your plan’s max_page_size
pageint1Page number (page mode)
cursorstring—Cursor token (cursor mode)
paginatestringpageSet to cursor to use cursor pagination

​
Page mode

Page mode is the default. You navigate results using integer page numbers and can jump to any page directly. Each response includes a meta.pagination object with total counts and a links object with pre-built URLs for the next and previous pages. Fetch the first page with the default page size: 
curl -s "https://api.8bitedge.com/api/v1/games/titles" \
  -H "Authorization: Bearer $TOKEN" | jq

{
  "data": [
    { "id": 12, "display_game_name": "Aladdin" },
    { "id": 47, "display_game_name": "Battletoads" }
  ],
  "meta": { "pagination": { "mode": "page", "page": 1, "per_page": 25, "total": 842, "last_page": 34 } },
  "links": { "next": "https://api.8bitedge.com/api/v1/games/titles?page=2", "prev": null }
}
​
meta.pagination.mode
string
Always "page" in page mode.
​
meta.pagination.page
integer
The current page number.
​
meta.pagination.per_page
integer
The actual number of items per page used in this response (may be less than your requested limit if your plan caps it).
​
meta.pagination.total
integer
Total number of items across all pages.
​
meta.pagination.last_page
integer
The number of the final page.
​
links.next
string | null
Full URL to the next page, or null if you are on the last page.
​
links.prev
string | null
Full URL to the previous page, or null if you are on the first page.
To walk every page in a shell script, follow links.next until it becomes null: 
url="https://api.8bitedge.com/api/v1/games/titles?limit=50"
while [ "$url" != "null" ] && [ -n "$url" ]; do
  page=$(curl -s "$url" -H "Authorization: Bearer $TOKEN")
  echo "$page" | jq -c '.data[]'
  url=$(echo "$page" | jq -r '.links.next')
done

​
Cursor mode

Cursor mode is better suited for large or frequently-changing datasets. Instead of page numbers, the server returns an opaque cursor token pointing to your position in the result set. This means records are never skipped or duplicated when new items are inserted between requests — something page mode cannot guarantee. Opt in by adding paginate=cursor to your request: 
curl -s "https://api.8bitedge.com/api/v1/consoles?paginate=cursor&limit=10" \
  -H "Authorization: Bearer $TOKEN" | jq

{
  "data": [ { "id": 3, "console_name": "Nintendo 64" }, { "id": 7, "console_name": "Nintendo SNES" } ],
  "meta": { "pagination": { "mode": "cursor", "per_page": 10, "next_cursor": "eyJpZCI6N30", "prev_cursor": null } },
  "links": { "next": "https://api.8bitedge.com/api/v1/consoles?paginate=cursor&limit=10&cursor=eyJpZCI6N30", "prev": null }
}
​
meta.pagination.next_cursor
string | null
Pass this value as the cursor query parameter to fetch the next page. null when you have reached the end of the result set.
​
meta.pagination.prev_cursor
string | null
Pass this value as the cursor query parameter to go back one page. null on the first page.
Fetch subsequent pages by passing the returned cursor token in the cursor parameter: 
curl -s "https://api.8bitedge.com/api/v1/consoles?paginate=cursor&limit=10&cursor=eyJpZCI6N30" \
  -H "Authorization: Bearer $TOKEN" | jq
To walk all pages in cursor mode, loop until meta.pagination.next_cursor is null: 
cursor=""
while true; do
  if [ -n "$cursor" ]; then
    url="https://api.8bitedge.com/api/v1/consoles?paginate=cursor&limit=10&cursor=$cursor"
  else
    url="https://api.8bitedge.com/api/v1/consoles?paginate=cursor&limit=10"
  fi

  page=$(curl -s "$url" -H "Authorization: Bearer $TOKEN")
  echo "$page" | jq -c '.data[]'

  cursor=$(echo "$page" | jq -r '.meta.pagination.next_cursor')
  [ "$cursor" = "null" ] && break
done
Cursor tokens are opaque server-generated strings. Do not attempt to parse, decode, or construct them manually — their internal format may change without notice. Always use the cursor value exactly as returned in meta.pagination.next_cursor or links.next.

​
Plan caps

Your plan’s max_page_size places a hard ceiling on the limit you can request. If you pass a limit higher than your plan allows, the API silently uses your plan’s maximum instead — no error is returned. For example, if you request limit=500 on a Starter plan (whose max_page_size is 50), the response will contain at most 50 items with meta.pagination.per_page: 50.
Always read meta.pagination.per_page from the response to know the actual page size that was applied. Never assume your requested limit was honored — your plan may have silently capped it.