Search within a budget

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 max_results to cap the results you pay for. The iterator requests at most that many results and lowers the page size on its last request. max_results=0 makes no request.

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    count = client.search.count_people(
        current_function="Marketing", location={"countryCode": "FR"}
    )
    print("Matches:", count.data.count if count.data else None)  # free

    for person in client.search.iter_people(
        current_function="Marketing",
        location={"countryCode": "FR"},
        per_page=50,
        max_results=200,
    ):
        if person is not None:
            print(person.first_name, person.last_name)

The iterators are iter_people, iter_people_by_prompt, iter_people_lookalike, iter_organizations and iter_organizations_by_prompt. Set per_page from 1 to 100, or use the default of 25 results. 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 a page method such as client.search.people(). The returned page has data, next_cursor, count, quotas, has_next_page() and get_next_page(). Call get_next_page() to resend the same filters with the next cursor. The method returns None after the last page. Each page you request is billed for the profiles it returns.

Prompt searches also expose interpretation, the filters extracted from the prompt.

Separate result credits from prompt fees

max_results limits the number of profiles requested, not an absolute credit amount. Agentic Search adds 1 credit for each requested page, including an empty page. Budget for both returned results and prompt page fees.

A negative or non-integer max_results, or an iterator per_page outside 1 to 100, raises ReverseContactError. If you stop iterating, the SDK fetches no further pages. Results already delivered remain billed.

See client.search for all 15 methods and their parameters. Use Filter values as constants to choose typed values from fixed lists.

Return to the Python SDK overview.