Does Brave's offset parameter count results or result pages?

Definition: In Brave's Web Search API, offset is a zero-based page offset. It counts result pages of the size set by count, so the next page normally uses an offset one greater than the previous page. Brave also documents that adjacent pages can overlap.

Key facts

• Brave defines offset as the number of search result pages, measured in units of count, to skip before returning a result, in its Web Search API reference.
• count controls the number of web results returned, has a maximum of 20 and defaults to 20. The delivered number can be lower than requested, according to the same API reference.
• The reference uses offset=0 for the page at offset 0 and says to increment offset by 1 for each subsequent page, with 0, 1 and 2 as its example sequence.
• Brave's Web Search API code documentation shows page 2 with count=20&offset=1.
• Multiple pages can include overlapping results, and the response's query.more_results_available field indicates whether more pages are available.

How does the offset unit work?

The API reference pairs count and offset. count is the requested number of search results in the response. It applies to web results, has a minimum of 1, a maximum of 20 and a default of 20. The actual number delivered can be lower than the requested count.

offset starts at 0. The reference describes it as the number of result pages of size count to skip, with a default of 0 and a maximum of 9. With count=10, offset 0 is the page at the start of the sequence, offset 1 is the next page position and offset 2 is the following one. The unit is a page position. Individual results are addressed through the page size and page offset together.

count=10&offset=0
count=10&offset=1
count=10&offset=2

The sequence in the code block follows Brave's example of incrementing the offset by 1 for each subsequent page. It does not imply that every response contains exactly 10 results, because the reference says the actual number delivered may be lower.

What does Brave's second pagination guide show?

Brave's Web Search API code documentation describes count as the maximum number of results per page, with a maximum and default of 20. It describes offset as a zero-based starting position and labels offset=1 as page 2 when the request asks for up to 20 results per page.

curl "https://api.search.brave.com/res/v1/web/search?q=open+source+projects&count=20&offset=1" \
  -H "X-Subscription-Token: <YOUR_API_KEY>"

This example confirms the page-based reading of the parameter. It also gives a concrete request shape for the second page position: keep the query and count, then change the offset from 0 to 1.

How should a client handle overlap and the end of the sequence?

The API reference explicitly says that multiple pages can include some overlap in results. A client combining pages should therefore compare the returned result URLs before presenting one merged list, while retaining the original page order for pagination state.

The same reference exposes more_results_available in the query response object and defines it as whether more results are available for pagination. The code documentation says to inspect that field before requesting the next page and to request the next page only when its value is true.

{
  "query": {
    "original": "open source projects",
    "more_results_available": true
  }
}

The documented maximum offset is 9, so a client should also treat the API's continuation field as the signal for whether another request is appropriate instead of assuming that every offset from 0 through 9 has another page.

Related terms

• Brave Search API
• Does Brave's count setting also cap news and location results?
• How do I retrieve additional source passages from Brave Search API?

FAQ

If I request 10 results, what should the next offset be?

Use offset 1 after a page requested with count=10. The documented sequence is count=10 with offsets 0, 1, 2 and so on. The offset advances by page, while count sets the requested page size.

Can I assume each page has the requested number of results?

No. Brave says the actual number delivered may be less than requested, and it says multiple pages can overlap. Preserve each result's URL when merging pages and handle duplicates.

When should I stop requesting pages?

Check query.more_results_available. Brave's code documentation says to request the next page only when that field is true.

Sources

1. Brave Search API, "Search", undated
2. Brave Search API, "Web Search - Brave Search API", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer