Pagination

In this guide, we will look at how to work with paginated responses when querying the Brandsearch API. By default, all list endpoints return 20 results per page. You can request up to 100 results per page.

How pagination works

All list endpoints support page and page_size query parameters. Paginated responses include a pagination object with metadata about the current page.

Query parameters

Name
page
Type
integer
Description
The page number to return, starting from 1. Default is 1. Maximum is 1000.
Name
page_size
Type
integer
Description
The number of results per page. Default is 20. Minimum is 1, maximum is 100.

Paginated response

{
  "data": [
    { "id": "gymshark.com", "name": "www.gymshark.com" },
    { "id": "adidas.com", "name": "Adidas" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 150000,
    "total_pages": 7500
  }
}

Example

In this example, we request the second page of brands sorted by monthly visits, with 10 results per page.

Paginating through brands

curl -G https://api.brandsearch.co/v1/brands \
  -H "X-API-Key: bsk_your_api_key" \
  -d page=2 \
  -d page_size=10 \
  -d sort_by=monthly_visits \
  -d sort_order=desc

Pagination limits

A search can be paged through its first 10,000 results, or more on some searches. A page past them is a 400 invalid_parameter: details.max_page names the last page you can reach for your page_size, and details.max_results how many results the search can be paged through. Nothing is charged. To reach other results, narrow the filters or change the sort. Product search stops sooner, at its first 500 results, with at most 25 per page.