> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/javascript/search-budget
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# Search within a budget

> Count matches for free, cap requested results with maxResults, and paginate people or company searches with the Reverse Contact TypeScript SDK.

- Last verified: 2026-11-04

Count matches before reading paid search results.

## Count, then search

Search costs 1 credit per profile or company delivered. The two Agentic Search endpoints add 1 credit per page. Count matches for free first, then read the results with an iterator.

Every search iterator requires `maxResults` to cap the results you pay for. The iterator requests at most that many results and lowers `perPage` on its last request to stay within the cap. `maxResults: 0` makes no request.

**Count, then search**

```typescript [TypeScript SDK]
import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

const count = await client.search.countPeople({
  currentFunction: "Marketing",
  location: { countryCode: "FR" }
});
console.log("Matches:", count.data.count); // free

for await (const person of client.search.iterPeople(
  { currentFunction: "Marketing", location: { countryCode: "FR" }, perPage: 50 },
  { maxResults: 200 }
)) {
  console.log(person.firstName, person.lastName);
}
```

The iterators are `iterPeople`, `iterPeopleByPrompt`, `iterPeopleLookalike`, `iterOrganizations` and `iterOrganizationsByPrompt`. Set `perPage` between 1 and 100, or use the default of 25 results per page. An iterator fetches one page at a time, only when you read further. If the API repeats a cursor, the iterator stops with an error.

To work page by page, call `client.search.people()`. The returned page has `data`, `nextCursor`, `count`, `quotas`, `hasNextPage()` and `getNextPage()`. Use `getNextPage()` to send the same filters with the next cursor. The method returns `null` after the last page. Prompt searches also return `interpretation`, which contains the filters derived from the prompt.

`maxResults` caps delivered results, not total credits: Agentic Search adds a credit for each requested page. `hasNextPage()` only checks the cursor. `getNextPage()` sends a new request with the original filters. See [client.search](https://docs.reversecontact.com/sdk/javascript/search) for every method and [Filter values as constants](https://docs.reversecontact.com/sdk/javascript/filter-constants) for accepted catalog values.

## Read a page explicitly

A `Page` is a synchronous iterable: `for...of` reads only the items already loaded in that page. `page[Symbol.iterator]()` does not request another page. Call `getNextPage(options?)` to fetch more results. The optional argument accepts `RequestOptions` such as `timeout` and `signal`.

**Read one page, then the next**

```typescript [TypeScript SDK]
import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact();
const page = await client.search.people({ firstName: "Jane", perPage: 10 });
for (const person of page) console.log(person.firstName);

if (page.hasNextPage()) {
  const nextPage = await page.getNextPage({ timeout: 30_000 });
  console.log(nextPage?.data);
}
```

Each requested page is billed for the results delivered. Use a bounded iterator when you need `maxResults` to apply across pages.

Return to the [TypeScript SDK overview](https://docs.reversecontact.com/sdk/javascript).

## FAQ

### How do I cap the number of search results billed by the SDK?

Set the required `maxResults` option on a search iterator. The SDK reduces the last request size to stay within the result budget, and `maxResults: 0` sends no request.

### Does maxResults cap all credits used by Agentic Search?

`maxResults` caps returned profiles or companies. Agentic Search also costs 1 credit per requested page, in addition to 1 credit per result.

### Does the SDK fetch search pages before I need them?

Search iterators fetch one page at a time as results are consumed. `getNextPage()` explicitly requests the next page and returns `null` after the last page.