Preview leads (cheapest paid look)
preview_leadsRead-only
Preview leads at minimal cost to evaluate fit and select prospects for enrichment, avoiding full search expenses on unqualified candidates.
Instructions
Cheap look at the actual people behind a count, before committing to a full search. BILLABLE — about $0.002 per returned row (Tier 0 list price; your account may pay a different rate — call get_balance for your real prices, and read cost.amount_charged in every response for what was actually spent). Preview rows carry a Generect id, so the intended flow is: preview many → pick the few that fit → enrich_lead / generate_email only on those. Per the API contract preview rows are masked (no LinkedIn URL, domain, email or phone); if your account returns more than that, treat it as a bonus and not something to rely on.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Alias for limit_by. | |
| strict | No | Fields to match strictly, e.g. ["company_locations"]. | |
| compact | No | Default true: return a small per-lead summary (including the Generect `id`, which every later step accepts). Set false for the full raw record (~80 fields) — only worth it when you specifically need skills, education or other deep fields. | |
| keywords | No | Free-text keywords across headline/summary/skills — realtime only: using it forces the pricier live mode. | |
| limit_by | No | Rows to return this call (1–100, default 25). You are billed per returned row, so this number IS the price of the call. | |
| personas | No | Advanced raw persona tuples [name, functions, seniorities, prohibits, priority?] — realtime only: using it forces the pricier live mode. | |
| functions | No | Job functions, e.g. ["Sales","Marketing","Engineering"] — realtime only: using it forces the pricier live mode. | |
| job_title | No | DEPRECATED alias for job_titles. Still honoured: it is merged into job_titles. | |
| locations | No | Where the lead lives — matches cities, states and countries, e.g. ["United States","Berlin"]. | |
| offset_by | No | Rows to skip (pagination). | |
| company_id | No | Anchor to one company by LinkedIn numeric id. | |
| count_only | No | Return just how many leads the preview index holds for these filters and spend nothing. Free. This is a second opinion on count_leads: preview and cached search are different indexes and can disagree. | |
| job_titles | No | Target job titles, OR-matched (e.g. ["CEO","Founder","Owner"]). A lead needs to match only one. | |
| timeout_ms | No | Request timeout in milliseconds. | |
| exclude_ids | No | Skip leads by Generect/Sales-Navigator id. Pass the ids you already received to paginate without duplicates — ordering is not stable, so this is more reliable than offset. | |
| seniorities | No | Seniority at the current employer, e.g. ["Owner","CXO","VP","Director","Manager"]. Current position only. | |
| changed_jobs | No | Only leads who recently changed jobs — realtime only: using it forces the pricier live mode. | |
| company_link | No | Anchor to one company by LinkedIn URL. | |
| company_name | No | Anchor to one company by name (exclusive with company_link/company_id). | |
| company_types | No | Employer types: "Public Company","Privately Held","Non Profit","Government Agency","Educational","Self Employed","Self Owned","Partnership". | |
| exclude_names | No | Skip leads by full name. KNOWN ISSUE: in database mode any non-empty value collapses the result set to 0 (verified 2026-08-09); it behaves correctly in realtime mode. Prefer exclude_ids, or filter names out yourself after the search. | |
| get_max_leads | No | DEPRECATED — accepted but ignored. Always on now: search responses include results_count without asking. | |
| company_filters | No | Optional company-level filters for a two-level ICP. | |
| lead_industries | No | DEPRECATED — accepted but ignored. Removed: v1 filters on the employer's industry. Use company_industries. | |
| without_company | No | DEPRECATED — accepted but ignored. No longer needed — v1 filter-only search is the default when no company anchor is set. | |
| years_in_company | No | Time at current company, same buckets as years_in_position — realtime only: using it forces the pricier live mode. | |
| company_locations | No | HQ location of the lead's current employer. | |
| confirm_spend_usd | No | Explicit approval for an unusually large charge. Calls whose worst case exceeds $5 are refused unless this is set to at least the amount the tool reports. Only set it after the user has agreed to that number. | |
| exclude_locations | No | Lead locations to exclude. | |
| filter_empty_vars | No | Drop leads where these fields are empty, e.g. ["profile_photo","job_started_on"]. Useful to raise data quality before paying. | |
| years_in_position | No | Time in current role: 1=<1y, 2=1-2y, 3=3-5y, 4=6-10y, 5=10y+ — realtime only: using it forces the pricier live mode. | |
| company_headcounts | No | Employer size buckets. Allowed ONLY: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10 000+" (note the space in "10 000+"). | |
| company_industries | No | Industry of the current employer. Must match Generect industry names exactly (e.g. "Software Development", "Financial Services"); names are hierarchical and unknown names are rejected with HTTP 400 naming the field. | |
| past_company_names | No | Companies the lead previously worked at (alumni targeting) — realtime only: using it forces the pricier live mode. | |
| posted_on_linkedin | No | Only leads who recently posted on LinkedIn — realtime only: using it forces the pricier live mode. | |
| linkedin_filter_link | No | A LinkedIn / Sales Navigator search URL to lift filters from — realtime only: using it forces the pricier live mode. | |
| allow_unlisted_values | No | Escape hatch. This server checks industry / seniority / headcount / company-type values against the LinkedIn vocabularies before sending, because the API silently returns 0 results for an unknown industry or seniority instead of rejecting it. Set true only when you are sure a value is valid and this server is out of date. | |
| exclude_title_keywords | No | DEPRECATED — accepted but ignored. No v1 equivalent. Narrow job_titles instead, or filter the returned rows yourself. | |
| exclude_company_locations | No | Employer HQ locations to exclude. | |
| exclude_company_headcounts | No | Employer size buckets to exclude. | |
| exclude_company_industries | No | Employer industries to exclude. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | ||
| cost | No | ||
| mode | No | ||
| note | No | ||
| leads | No | ||
| status | No | ||
| returned | No | ||
| companies | No | ||
| test_mode | No | ||
| spend_guard | No | ||
| results_count | No | ||
| next_page_args | No | ||
| requested_rows | No | ||
| escalation_note | No | ||
| test_mode_notice | No | ||
| vocabulary_warnings | No | ||
| blocked_by_vocabulary | No | ||
| deprecated_params_ignored | No | ||
| escalated_to_realtime_because | No | ||
| api_returned_more_than_requested | No |