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

# Pagination

> Page through search results with limit, offset, and hasMore

Only `POST /statutes/search` is paginated. Two request fields control the window, and one response flag tells you when to stop.

## Request parameters

| Field    | Type | Default | Range   | Purpose                                    |
| -------- | ---- | ------- | ------- | ------------------------------------------ |
| `limit`  | int  | 10      | 1 to 50 | Page size, the number of results returned  |
| `offset` | int  | 0       | 0 to 40 | Number of results to skip before this page |

## Response fields

Each search response includes these top-level fields:

* `results`: the array of result objects for this page.
* `total`: the count of results returned on **this page**, not the corpus-wide match count.
* `offset`: the offset that was applied.
* `hasMore`: `true` when more results are reachable beyond this page.

<Warning>
  `total` is a per-page count, not a corpus total. There is no field that reports how many sections in the whole corpus match your query. Use `hasMore` to drive your loop, not arithmetic on `total`.
</Warning>

## How deep you can page

The deepest reachable result is `offset + limit`. Because `offset` is capped at `40` (the reranking window), the furthest you can page is offset `40` plus your `limit`. To reach the last results, request the largest page size:

```json theme={"theme":"github-dark"}
{ "query": "data breach notification", "limit": 50, "offset": 40 }
```

<Note>
  If you need to survey a jurisdiction more broadly, scope with `corpusType` and `state` and run several narrower queries rather than trying to page past the window. Tighter scope also gives more predictable pages.
</Note>

## Page until hasMore is false

This loop walks every reachable page, stopping when `hasMore` is `false` or the offset cap is reached.

<CodeGroup>
  ```python Python theme={"theme":"github-dark"}
  import requests

  def search_all(query, corpus_type=None, state=None, page_size=50):
      url = "https://api.vaquill.ai/api/v1/statutes/search"
      headers = {
          "Authorization": "Bearer vq_key_...",
          "Content-Type": "application/json",
      }
      results = []
      offset = 0
      while True:
          body = {"query": query, "limit": page_size, "offset": offset}
          if corpus_type:
              body["corpusType"] = corpus_type
          if state:
              body["state"] = state

          data = requests.post(url, headers=headers, json=body).json()
          results.extend(data["results"])

          # Stop when the API says there is no more, or we hit the offset cap.
          if not data["hasMore"] or offset >= 40:
              break
          offset = min(offset + page_size, 40)

      return results

  sections = search_all("data breach notification", corpus_type="STATE", state="ca")
  print(len(sections))
  ```

  ```javascript JavaScript theme={"theme":"github-dark"}
  async function searchAll(query, { corpusType, state, pageSize = 50 } = {}) {
    const url = "https://api.vaquill.ai/api/v1/statutes/search";
    const headers = {
      Authorization: "Bearer vq_key_...",
      "Content-Type": "application/json",
    };
    const results = [];
    let offset = 0;

    while (true) {
      const body = { query, limit: pageSize, offset };
      if (corpusType) body.corpusType = corpusType;
      if (state) body.state = state;

      const data = await (
        await fetch(url, { method: "POST", headers, body: JSON.stringify(body) })
      ).json();
      results.push(...data.results);

      if (!data.hasMore || offset >= 40) break;
      offset = Math.min(offset + pageSize, 40);
    }
    return results;
  }

  const sections = await searchAll("data breach notification", {
    corpusType: "STATE",
    state: "ca",
  });
  console.log(sections.length);
  ```
</CodeGroup>

## Related

<CardGroup cols={2}>
  <Card title="Rate limits" icon="gauge-high" href="/docs/api-guide/rate-limits">
    Stay under per-minute limits while paging in a loop.
  </Card>

  <Card title="Best practices" icon="circle-check" href="/docs/api-guide/best-practices">
    Scope queries for tighter, more predictable pages.
  </Card>
</CardGroup>