docs sourcing
Search plans
A disjoint tier ladder, a summary, and a free estimate.
POST /v1/search-plans turns an intent into tiers of queries with a summary and an estimate. Send intent_id, or an inline intent and/or job_description. target is 30 to 60 candidates (default 40; company-first allows 20). max_pages caps the plan at up to 45 pages.
Tiers
The ladder starts narrow and widens: exact titles near the city, then the rest of the country, then adjacent titles. Preferred companies come first when you named any. Each tier has:
| Field | Meaning |
|---|---|
id | Unique in the plan, such as exact_title_local or exact_title_local+filters |
label | For people: "Exact title, local" |
rank | Search order. Lower first |
kind | company, exact, adjacent, both, or schools |
queries[] | query_key, the filters sent to the person index, the part, and already_paid_pages |
skip_reason | Why a tier was not used: already_covered, no_titles, companies_not_found, or schools_unsupported |
Tiers are disjoint: a country tier excludes the local location ids, and an adjacent tier excludes the exact titles. No person is paid for twice across tiers. A query's part says how a broad tier is split: tools first (keyword_first), then the experience window (in_window), then the rest (remainder), or not split (unsplit).
summary describes the plan in one paragraph a recruiter can read. applied_filters, ignored_fields, and warnings carry over from the intent.
Estimate
| Field | Meaning |
|---|---|
credits_min | One lead (1 credit) when the next page still has to be fetched, or 0 when that page is cached. An empty page is not charged |
credits_max | The ceiling: pages plus expected live profiles at 2 each. A run never spends more than its budget |
expected_pages, expected_profile_fetches | What the ceiling assumes |
skipped_pages_from_checkpoints | Pages earlier runs already paid for |
balance_credits | Your balance now |
GET /v1/search-plans/{plan_id} returns a plan again with the estimate recomputed against today's balance.
What it costs
Free. Company names are resolved from the built-in list and your cache while planning; a name that needs a live lookup is left out and reported, and you can resolve it with POST /v1/companies:resolve (1 credits per new company).
Reference: createSearchPlan in the API reference.