Skip to main content
Each page of Business Search results is a new search against the current index, not a fixed snapshot.

​
How do you request the next page?

Set offset to the number of results to skip and limit to the page size. offset starts at 0 and has no maximum. limit defaults to 10, and its maximum depends on the mode: This body skips the first 20 results and requests the next 20:
Repeat the same category, source, mode, query and view while changing offset. Changing any other property starts a different search. An offset beyond meta.matched does not return an empty page. The request fails with HTTP 500 and error_code backend_search_failed, so stop paging on a short page and treat that 500 as the end of the set rather than an outage. The index refreshes daily, so results and their order can change between requests. A record on page 1 of one run can appear on page 2 of the next.

​
How do you read the response metadata?

  • meta.offset and meta.limit echo the requested pagination.
  • documents.length is the actual number of records returned in this page. It can be smaller than limit.
  • meta.matched reports how many matches the search reached. Treat it as a lower bound rather than an exhaustive count, particularly for text and natural-language searches. It can change between modes or requests.
  • meta.coverage_percent reports the share of the index that answered. A value below 100 means partial coverage. A value of 100 does not mean every relevant record was returned or every field was populated.

​
What must you not do with meta.matched?

Do not use meta.matched to size a dataset or to tell users that exactly that many companies or people satisfy their intent. It is a search-reach figure, not a census. If a successful response contains no documents, it means the request returned no matches, not that no such entity exists.
Surface coverage to the reader when it matters. A results page built on a response with coverage_percent below 100 should say the result set is partial rather than presenting it as complete.

​
Frequently asked questions

​
When should a paging loop stop?

Stop when documents comes back empty or shorter than limit. Do not page until offset reaches meta.matched, because meta.matched is a lower bound and can change between requests.

​
Why did the same offset return different records?

Each page is a fresh search against the current index. If your job needs a stable set, collect the pages in one pass and deduplicate on bright_id plus source rather than re-fetching a page later.

​
How large can limit be?

limit defaults to 10. The ceiling is 100 per page in Ludicrous and Instant and 10 per page in Smart. It is the requested maximum for one page, so the returned array can be shorter than the value you send.

​
How often does the index update?

Daily. A record added or changed at the source appears in Business Search results after the next daily refresh.