Skip to content

Autonomous AI sales agent powered by Claude Code or Codex. Finds prospects, writes cold emails, sends campaigns, handles replies, books meetings. No API keys needed — runs on your Claude or Codex subscriptions.

Share one configurable Hunter budget across all domain-searches

Ethan55908b067bee
diff --git a/.env.example b/.env.example
index 3c5b462..8642a25 100644
--- a/.env.example
+++ b/.env.example
@@ -80,6 +80,9 @@ ZEROBOUNCE_API_KEY=
# Harvey verifies one address instead of guessing six).
# Where to get it: https://hunter.io → sign up → API → API Keys
HUNTER_API_KEY=
+# Domain-searches per month across all of Harvey. 25 matches Hunter's free
+# tier; set this to your plan's allowance if you pay for Hunter.
+HUNTER_MONTHLY_SEARCHES=25
# ------------------------------------------------------------
# DISCOVERY — where Harvey finds businesses. [ALL OPTIONAL]
diff --git a/harvey/agents/scout.py b/harvey/agents/scout.py
index 3ca6e39..e0fe194 100644
--- a/harvey/agents/scout.py
+++ b/harvey/agents/scout.py
@@ -59,12 +59,10 @@ MAX_RESULTS_PER_QUERY = 20
MAX_COMPANIES_PER_CYCLE = 10
MAX_PROSPECTS_PER_CYCLE = 25
-# Hunter's free tier is 25 domain-searches/month total, and each call costs
-# a credit regardless of how many people it returns — a heartbeat running
-# every 15 minutes would blow through that in under an hour uncapped, so
-# usage is tracked explicitly (see _prospect_via_hunter) rather than trusted
-# to fail gracefully once exhausted.
-HUNTER_MONTHLY_CAP = 25
+# Hunter domain-searches per heartbeat. The monthly budget itself is shared
+# with email-pattern lookups and set by HUNTER_MONTHLY_SEARCHES (see
+# integrations/email_finder.py); this just paces it, since a heartbeat every
+# 15 minutes would spend a free-tier month in a few hours otherwise.
HUNTER_DOMAINS_PER_CYCLE = 1
# Rotate a small pool of realistic desktop user-agents. Scrapers that always
@@ -134,8 +132,8 @@ class Scout:
strategies = []
# Hunter first, if configured: real named people with a real
# verification verdict beats a scrape guess, but the free tier's
- # 25/month cap means it only ever covers a handful of companies —
- # self-skips once the monthly quota (tracked in settings) is spent.
+ # monthly budget (HUNTER_MONTHLY_SEARCHES, 25 by default) is small —
+ # self-skips once it's spent.
strategies.append(("hunter", self._prospect_via_hunter))
# Backfill next: companies already on file (e.g. from `harvey
# discover`) but with zero prospects. Scrapes each company's own
@@ -484,21 +482,18 @@ class Scout:
"""Pull Hunter's actual named-people data for companies with zero
prospects — real name/title/email/verification, not a scrape guess.
- Hunter's free tier is 25 domain-searches/month for the whole
- account, so this draws from the same rotating pool as the team-page
- backfill but at a much smaller, explicitly quota-tracked pace.
+ Draws from the same rotating pool as the team-page backfill, but at
+ a much smaller pace and against the shared monthly Hunter budget.
"""
api_key = getattr(self.env, "hunter_api_key", "") or ""
if not api_key:
return 0
- month_key = datetime.now(timezone.utc).strftime("%Y-%m")
- setting_key = f"hunter_domain_search_count:{month_key}"
- try:
- used = int(await self.state.get_setting(setting_key, "0") or "0")
- except ValueError:
- used = 0
- remaining = HUNTER_MONTHLY_CAP - used
+ from harvey.integrations.email_finder import (
+ hunter_domain_people, hunter_searches_remaining, record_hunter_search,
+ )
+
+ remaining = await hunter_searches_remaining(self.state)
if remaining <= 0:
return 0
@@ -511,8 +506,6 @@ class Scout:
if not companies:
return 0
- from harvey.integrations.email_finder import hunter_domain_people
-
default_industry = (
self.config.icp.industries[0] if self.config.icp.industries else ""
)
@@ -522,12 +515,10 @@ class Scout:
if not domain:
continue
+ if await hunter_searches_remaining(self.state) <= 0:
+ break
+ await record_hunter_search(self.state)
people = await hunter_domain_people(domain, api_key)
- used += 1
- try:
- await self.state.set_setting(setting_key, str(used))
- except Exception as e:
- logger.debug(f"set_setting failed for {setting_key}: {e}")
try:
await self.state.mark_prospects_checked(company["id"])
except Exception as e:
@@ -575,9 +566,6 @@ class Scout:
if count >= MAX_PROSPECTS_PER_CYCLE:
return count
- if used >= HUNTER_MONTHLY_CAP:
- break
-
return count
# ── Strategy 0: Known companies with zero prospects ──
diff --git a/harvey/integrations/email_finder.py b/harvey/integrations/email_finder.py
index 173882c..733ecd7 100644
--- a/harvey/integrations/email_finder.py
+++ b/harvey/integrations/email_finder.py
@@ -25,6 +25,7 @@ import os
import random
import re
from dataclasses import dataclass
+from datetime import datetime, timezone
from typing import Optional
import dns.resolver
@@ -230,6 +231,55 @@ def _hunter_api_key() -> str:
return os.getenv("HUNTER_API_KEY", "").strip()
+# Hunter's free tier is 25 domain-searches/month for the whole account, and
+# every call spends one no matter how many people it returns. Paid plans set
+# HUNTER_MONTHLY_SEARCHES to their own allowance. Every domain-search call in
+# Harvey draws from this one counter, so the pattern lookup and Scout's
+# named-contact strategy can't each assume they have the full quota.
+HUNTER_FREE_MONTHLY_SEARCHES = 25
+
+
+def _hunter_monthly_cap() -> int:
+ raw = os.getenv("HUNTER_MONTHLY_SEARCHES", "").strip()
+ if not raw:
+ return HUNTER_FREE_MONTHLY_SEARCHES
+ try:
+ return max(int(raw), 0)
+ except ValueError:
+ return HUNTER_FREE_MONTHLY_SEARCHES
+
+
+def _hunter_usage_key() -> str:
+ return f"hunter_domain_search_count:{datetime.now(timezone.utc):%Y-%m}"
+
+
+async def hunter_searches_remaining(state) -> int:
+ """Domain-searches left this calendar month (UTC). Without a state
+ store there is nothing to count against, so the full cap is reported."""
+ cap = _hunter_monthly_cap()
+ if state is None:
+ return cap
+ try:
+ used = int(await state.get_setting(_hunter_usage_key(), "0") or "0")
+ except (ValueError, TypeError):
+ used = 0
+ except Exception as e:
+ logger.debug(f"Hunter usage read failed: {e}")
+ return 0
+ return max(cap - used, 0)
+
+
+async def record_hunter_search(state) -> None:
+ """Count one domain-search against this month's budget. Called before
+ the request, so a call that fails mid-flight is still counted."""
+ if state is None:
+ return
+ try:
+ await state.increment_setting(_hunter_usage_key())
+ except Exception as e:
+ logger.debug(f"Hunter usage write failed: {e}")
+
+
async def hunter_domain_people(
domain: str, api_key: str, limit: int = 10
) -> Optional[list[dict]]:
@@ -238,9 +288,9 @@ async def hunter_domain_people(
and its own verification verdict). Returns the raw ``emails`` list, or
None on any failure (network, non-200, bad JSON, or no data).
- Costs one domain-search credit per call regardless of ``limit`` — the
- free tier is 25/month, so callers must budget calls, not rely on this
- failing gracefully to protect the quota.
+ Costs one domain-search credit per call regardless of ``limit``, so
+ callers must check hunter_searches_remaining() and record_hunter_search()
+ first rather than rely on this failing gracefully to protect the quota.
"""
try:
async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:
@@ -290,7 +340,8 @@ async def derive_pattern(
return inferred, "known_email", 0.9
key = _hunter_api_key()
- if key:
+ if key and await hunter_searches_remaining(state) > 0:
+ await record_hunter_search(state)
result = await _hunter_domain_pattern(domain, key)
if result:
return result[0], "hunter_domain_search", result[1]
diff --git a/tests/test_email_finder.py b/tests/test_email_finder.py
index e2236d3..ec68ca0 100644
--- a/tests/test_email_finder.py
+++ b/tests/test_email_finder.py
@@ -219,3 +219,38 @@ async def test_find_email_inconclusive_is_guess_not_verified(state, monkeypatch)
result = await find_email("Jane", "Doe", "acme.com", env=Env(), state=state)
assert result.status == "guess"
assert not result.verified
+
+
+# ── shared Hunter domain-search budget ──
+
+
+async def test_hunter_budget_defaults_to_free_tier(state, monkeypatch):
+ monkeypatch.delenv("HUNTER_MONTHLY_SEARCHES", raising=False)
+ assert await ef.hunter_searches_remaining(state) == 25
+ await ef.record_hunter_search(state)
+ assert await ef.hunter_searches_remaining(state) == 24
+
+
+async def test_hunter_budget_follows_paid_plan_setting(state, monkeypatch):
+ monkeypatch.setenv("HUNTER_MONTHLY_SEARCHES", "500")
+ assert await ef.hunter_searches_remaining(state) == 500
+
+
+async def test_derive_pattern_spends_and_respects_hunter_budget(state, monkeypatch):
+ monkeypatch.setattr(ef, "_hunter_api_key", lambda: "k")
+ monkeypatch.setenv("HUNTER_MONTHLY_SEARCHES", "1")
+ calls = []
+
+ async def fake_hunter(domain, key):
+ calls.append(domain)
+ return "{f}.{l}", 0.8
+
+ monkeypatch.setattr(ef, "_hunter_domain_pattern", fake_hunter)
+ _, source, _ = await derive_pattern("first-co.com", state=state)
+ assert source == "hunter_domain_search"
+ _, source, _ = await derive_pattern("second-co.com", state=state)
+ assert source == "default"
+ assert calls == ["first-co.com"]