> ## Documentation Index
> Fetch the complete documentation index at: https://galejames.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle pagination

> Retrieve paginated results from the BookHub Publisher API using `page` and `limit` parameters.

Use pagination to limit the number of results per page for a `GET /v2/books` request with a large book dataset.

## Prerequisites

Before you begin, ensure you meet the following prerequisites:

* Familiarity with BookHub Publisher API v2.
* A valid JWT for authentication.
* Access to your codebase that integrates with the BookHub Publisher API v2.

## Step 1: Send a paginated request

To implement pagination with the BookHub Publisher API, construct a request that fetches results in pages using the `page` and `limit` parameters.

The following examples use `page` and `limit` only. The endpoint also accepts `status`, `sort`, and `order` parameters — see [Get all books](/reference/reference-api-endpoints#get-all-books) for details.

```python theme={null}
def fetch_all_books(base_url, token):
    all_books = []
    page = 1
    while True:
        response = requests.get(
            f"{base_url}/v2/books",
            params={'page': page, 'limit': 20},
            headers={'Authorization': f'Bearer {token}'}
        )
        response.raise_for_status()
        data = response.json().get('data', {})
        if 'pagination' not in data:
            break
        all_books.extend(data.get('books', []))
        if page >= data['pagination']['totalPages']:
            break
        page += 1
    return all_books
```

> [!NOTE]
>
> The loop exits when `page` reaches `totalPages`. If the API returns fewer items than `limit`, stop after processing that page. If the response does not include a `pagination` object, exit immediately.

The response includes a `pagination` object with the total number of items, total pages, and current page.

```json theme={null}
{
  "status": "success",
  "data": {
    "books": [
      {
        "bookId": "123e4567-e89b-41d4-a716-426614174000",
        "title": "The Great Adventure",
        "author": "Jane Smith",
        "description": "An epic tale of courage and discovery",
        "language": "en-US",
        "publisher": "Adventure Books Inc",
        "publishedDate": "2024-03-15",
        "isbn": "978-0-1234-5678-9",
        "price": 24.99,
        "status": "ACTIVE",
        "coverImages": [
          "https://covers.bookhub.com/great-adventure-front.jpg"
        ],
        "genres": [
          "Fiction",
          "Adventure"
        ],
        "bookFormat": "Hardcover",
        "createdDate": "2024-12-25T10:30:00Z",
        "updatedDate": "2024-12-26T15:45:00Z"
      },
      {
        "bookId": "123e4567-e89b-41d4-a716-426614174001",
        "title": "Mystery at Midnight",
        "author": "Bob Johnson",
        "description": "A gripping mystery set in a small town",
        "language": "en-US",
        "publisher": "Midnight Press",
        "publishedDate": "2024-06-10",
        "isbn": "978-1-23-456789-0",
        "price": 19.99,
        "status": "ACTIVE",
        "coverImages": [
          "https://covers.bookhub.com/mystery-midnight-front.jpg"
        ],
        "genres": [
          "Mystery",
          "Thriller"
        ],
        "bookFormat": "Paperback",
        "createdDate": "2024-12-24T14:20:00Z",
        "updatedDate": "2024-12-24T14:20:00Z"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 87,
      "itemsPerPage": 20
    }
  }
}
```

### Error handling

The `page` parameter defaults to 1. The `limit` parameter accepts values between 1 and 100 and defaults to 20.

| Code | Cause | Resolution |
| - | - | - |
| `400` | Bad request (for example, invalid `page` or `limit` parameter) | Provide a valid `page` or `limit` parameter and try again. |
| `401` | Unauthorized (for example, a missing or invalid JWT) | Provide a valid JWT and try again. |
| `429` | Rate limit exceeded (for example, 150 requests per minute) | Wait until the time in the `X-RateLimit-Reset` header, then retry with the same `Idempotency-Key`. See [Monitor rate limits](/how-to-guides/how-to-guides-monitor-rate-limits). |

## Step 2: Test your implementation

Call the `fetch_all_books` function with your API base URL and JWT. Verify that it retrieves all books across multiple pages by checking the length of the returned list against `totalItems`.

```python theme={null}
BASE_URL = "https://api.bookhub.com/api"
TOKEN = "YOUR_JWT_TOKEN"
books = fetch_all_books(BASE_URL, TOKEN)
print(f"Total books fetched: {len(books)}")
```

## Next steps

Explore related topics:

### How-to guides

* [Cache book details for faster performance](/how-to-guides/how-to-guides-cache-book-details) — Use ETag and Cache-Control headers to cache book details and reduce unnecessary API calls.
* [Monitor rate limits](/how-to-guides/how-to-guides-monitor-rate-limits) — Track your API usage to avoid exceeding rate limits.

### Reference

* [Release notes](/reference/reference-release-notes) — Explore all changes in BookHub Publisher API v2, including any updates related to pagination.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.