Search within a budget

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.

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 for every method and Filter values as 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.

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.