> ## Documentation Index
> Fetch the complete documentation index at: https://docs.8bitedge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to paginate 8bitedge API results: page and cursor modes

> All 8bitedge list endpoints support page-based and cursor-based pagination. Learn how to use both modes and walk large result sets.

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:

| Param      | Type   | Default | Notes                                            |
| ---------- | ------ | ------- | ------------------------------------------------ |
| `limit`    | int    | 25      | Page size; capped by your plan's `max_page_size` |
| `page`     | int    | 1       | Page number (page mode)                          |
| `cursor`   | string | —       | Cursor token (cursor mode)                       |
| `paginate` | string | `page`  | Set 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:

```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/games/titles" \
  -H "Authorization: Bearer $TOKEN" | jq
```

```json theme={null}
{
  "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 }
}
```

<ResponseField name="meta.pagination.mode" type="string">
  Always `"page"` in page mode.
</ResponseField>

<ResponseField name="meta.pagination.page" type="integer">
  The current page number.
</ResponseField>

<ResponseField name="meta.pagination.per_page" type="integer">
  The actual number of items per page used in this response (may be less than your requested `limit` if your plan caps it).
</ResponseField>

<ResponseField name="meta.pagination.total" type="integer">
  Total number of items across all pages.
</ResponseField>

<ResponseField name="meta.pagination.last_page" type="integer">
  The number of the final page.
</ResponseField>

<ResponseField name="links.next" type="string | null">
  Full URL to the next page, or `null` if you are on the last page.
</ResponseField>

<ResponseField name="links.prev" type="string | null">
  Full URL to the previous page, or `null` if you are on the first page.
</ResponseField>

To walk every page in a shell script, follow `links.next` until it becomes `null`:

```bash theme={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:

```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/consoles?paginate=cursor&limit=10" \
  -H "Authorization: Bearer $TOKEN" | jq
```

```json theme={null}
{
  "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 }
}
```

<ResponseField name="meta.pagination.next_cursor" type="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.
</ResponseField>

<ResponseField name="meta.pagination.prev_cursor" type="string | null">
  Pass this value as the `cursor` query parameter to go back one page. `null` on the first page.
</ResponseField>

Fetch subsequent pages by passing the returned cursor token in the `cursor` parameter:

```bash theme={null}
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`:

```bash theme={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
```

<Note>
  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`.
</Note>

## 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`.

<Tip>
  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.
</Tip>