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

# Pagination

> Organize your search results with pagination in InstantSearch Android.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

Pagination gives you complete control over how you retrieve query results. You can:

* Implement standard paging
* Retrieve specific record subsets that ignore page boundaries.
* Set pagination defaults at indexing time
* Override pagination default settings at query time.

## Pagination at indexing time

At indexing time, you can set up two defaults:

* [`hitsPerPage`](/doc/api-reference/api-parameters/hitsPerPage): the number of hits returned for every page
* [`paginationLimitedTo`](/doc/api-reference/api-parameters/paginationLimitedTo): controls the number of hits retrieved for a given query

## Pagination at query time

You can:

* Retrieve a specific page with the [`page`](/doc/api-reference/api-parameters/page) parameter
* Specify specific record subsets by using the [`offset`](/doc/api-reference/api-parameters/offset) and [`length`](/doc/api-reference/api-parameters/length) parameters
* Override the default for `hitsPerPage`

## Response details

Algolia includes information about pagination in the API response.

```json JSON icon=braces theme={"system"}
{
  "page": 0,
  "nbHits": 40,
  "nbPages": 2,
  "hitsPerPage": 20,
  "exhaustiveNbHits": true
}
```

* `page` returns the current page (this value **starts at 0**)
* `hitsPerPage` returns the maximum number of hits returned for each page
* `nbPages` returns the number of pages available for the current query
* `nbHits` returns the number of hits that the search query matched
* `exhaustiveNbHits` returns a boolean indicating if the nbHits count was exhaustive or approximate
* `exhaustiveTypo` returns a boolean indicating if the typo-tolerance search was exhaustive or approximate (only included when typo-tolerance is enabled)

### No hits or is the search still in progress?

You should cater for situations when there are no hits (`nbHits` = 0) by [displaying a message to users and clearing filters](/doc/guides/building-search-ui/going-further/conditional-display/android#handling-no-results) so they can start over.

Sometimes, though, no hits can be reported if the user's device [can't access the network or the network connection is slow](/doc/guides/building-search-ui/going-further/improve-performance/android).
To determine if there are no hits for a query or if the search is still in progress, examine the value of InstantSearch's [`onLoadingChanged`](/doc/api-reference/widgets/instantsearch/android#param-on-loading-changed) event.
Consider adding a [loading indicator](/doc/guides/building-search-ui/going-further/improve-performance/android#add-a-loading-indicator) to inform users on a slow connection that their search is still in progress.

### Exhaustive hits

Usually, Algolia returns an accurate number of total hits.
However, if a query returns many hits, Algolia approximates the count to avoid scanning the whole <Index />.
This approximation protects other search and indexing operations.
If your API response includes the [`exhaustive.nbHits`](/doc/rest-api/search/search-single-index#response-exhaustive) parameter,
[the number of hits is approximate](https://support.algolia.com/hc/en-us/articles/4406975248145-Why-are-my-facet-and-hit-counts-not-accurate-).

## Retrieve specific pages

At query time, you can pass in the [`page`](/doc/api-reference/api-parameters/page) parameter to access a specific results page.
The [`hitsPerPage`](/doc/api-reference/api-parameters/hitsPerPage) parameter provides a way to set the default number of hits returned for each page. By default, its value is **20**. However, this can be overridden as an index setting or as a query parameter.

## Pagination limitations

### Default number of hits per query

By default, Algolia includes up to 1,000 hits per query.

### Overriding the default limits

You can adjust the number of hits in a paginated query with the [`paginationLimitedTo`](/doc/api-reference/api-parameters/paginationLimitedTo) parameter:

<CodeGroup>
  ```cs C# theme={"system"}
  var response = await client.SetSettingsAsync(
    "INDEX_NAME",
    new IndexSettings { PaginationLimitedTo = 1000 }
  );
  ```

  ```dart Dart theme={"system"}
  final response = await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(
      paginationLimitedTo: 1000,
    ),
  );
  ```

  ```go Go theme={"system"}
  response, err := client.SetSettings(client.NewApiSetSettingsRequest(
    "INDEX_NAME",
    search.NewEmptyIndexSettings().SetPaginationLimitedTo(1000)))
  if err != nil {
    // handle the eventual error
    panic(err)
  }
  ```

  ```java Java theme={"system"}
  UpdatedAtResponse response = client.setSettings("INDEX_NAME", new IndexSettings().setPaginationLimitedTo(1000));
  ```

  ```js JavaScript theme={"system"}
  const response = await client.setSettings({
    indexName: 'theIndexName',
    indexSettings: { paginationLimitedTo: 1000 },
  });
  ```

  ```kotlin Kotlin theme={"system"}
  var response =
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(paginationLimitedTo = 1000),
    )
  ```

  ```php PHP theme={"system"}
  $response = $client->setSettings(
      'INDEX_NAME',
      ['paginationLimitedTo' => 1000,
      ],
  );
  ```

  ```python Python theme={"system"}
  response = client.set_settings(
      index_name="INDEX_NAME",
      index_settings={
          "paginationLimitedTo": 1000,
      },
  )
  ```

  ```ruby Ruby theme={"system"}
  response = client.set_settings("INDEX_NAME", Algolia::Search::IndexSettings.new(pagination_limited_to: 1000))
  ```

  ```scala Scala theme={"system"}
  val response = Await.result(
    client.setSettings(
      indexName = "INDEX_NAME",
      indexSettings = IndexSettings(
        paginationLimitedTo = Some(1000)
      )
    ),
    Duration(100, "sec")
  )
  ```

  ```swift Swift theme={"system"}
  let response = try await client.setSettings(
      indexName: "INDEX_NAME",
      indexSettings: IndexSettings(paginationLimitedTo: 1000)
  )
  ```
</CodeGroup>

The maximum value is 20,000 hits per query.
Increasing the pagination limit might decrease performance.
Only set this number as large as necessary.

### Paging beyond the limit

If you request a page that is out-of-range (`page >= nbPages`),
Algolia doesn't return an error but 0 results.

## Retrieve a subset of records (with offset and length)

In most cases, you only need `page` and `hitsPerPage` to add pagination.
However, if you want to insert items, such as ads, into the results without affecting pagination, use the [`offset`](/doc/api-reference/api-parameters/offset) and [`length`](/doc/api-reference/api-parameters/length) parameters.
They let you specify the <Records /> to retrieve, not the page.

The `offset` parameter lets you specify the starting record, and `length` sets the number of records returned. For example, if you have 100 records in your result set, broken down into 10 pages (`hitsPerPage=10`), retrieve these subsets as follows (`offset` is zero-based):

* Records 50 to 80 (`offset=49` and `length = 30`).
* Records 21 to 25 (`offset=20` and `length = 5`).

<Info>
  With InstantSearch, you can only use `page` and `hitsPerPage` to implement pagination.
</Info>