> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/python/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 matching profiles for free, cap paid Python search results with max_results, and paginate people or company searches within your budget.

- Last verified: 2026-11-04

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.

**Count, then search**

```python [Python SDK]
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](https://docs.reversecontact.com/sdk/python/search) for all 15 methods and their parameters. Use [Filter values as constants](https://docs.reversecontact.com/sdk/python/filter-constants) to choose typed values from fixed lists.

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

## FAQ

### How do I cap the credits a Reverse Contact search spends in Python?

Use a free count method, then pass `max_results` to a search iterator to cap paid results. For prompt searches, also budget 1 credit per requested page.

### Does max_results=0 call the API?

A search iterator with `max_results=0` makes no HTTP request.

### What page size can I use for Python search iterators?

Search iterators accept `per_page` from 1 to 100, with a default of 25. The final request reduces the page size to the remaining `max_results` budget.

### How do I read search results one page at a time?

Use a page method such as `client.search.people()`, then `page.has_next_page()` and `page.get_next_page()`. Each requested page is billed for delivered results.