search_people is the widest surface in the API: sixteen parameters, most of them exact-match. The difference between a good search and a wasted one is almost always which filter you reach for, not how many you stack.
Start with a free count
search_linkedin_profile accepts count_only: true, which returns the number of matching results without fetching data or charging tokens. Use it to size a search before committing to it.
{ "name": "John Smith", "company_domain": "acme.com", "count_only": true }Tokens are only charged when data is found and returned. A search that matches nothing costs nothing — but it still counts against your rate limit.
Probe with limit: 1 before you pull a page
count_only is only available on search_linkedin_profile. On search_people there is no free dry run — so the cheapest way to check that a search is actually returning the people you meant is to run it with limit: 1.
{ "seniority": "VP", "department": "Sales", "industry": "Computer Software", "country": "United States", "limit": 1 }One record costs one search record against your fair use pool. The same query at limit: 25, walked five pages deep, costs 125 — and if a filter value was misspelt, a department/functional_area pair contradicted itself, or city matched a suburb you didn’t want, all 125 are spent on the wrong audience and can’t be refunded.
Read three things off the single result before you widen:
results.total— is the audience the size you expected? A total of 0 or 3 means a filter is wrong, not that the market is empty.The record itself — does this person actually match your intent? Check
title,seniority, location, and employer against what you asked for.business_emailandbusiness_email_risk_score— if you’re searching in order to email, confirm the emails are present and graded well enough to be worth pulling at volume.
Only when all three look right should you re-run with a larger limit and start paginating.
Search records are capped separately from enrichment records and are consumed per record returned, on a rolling 5-hour window. A single unchecked limit: 25 loop can burn a meaningful share of a plan’s pool before you notice the filters were wrong. See Rate Limits.
Filters are free precision
Search cost is driven by the free-text query, not by the filters attached to it.
Query shape | Speed and precision |
| Slower and less precise |
| Slower but more precise |
Filters alone, no | ~40× faster and more precise |
Two rules follow.
Never send a bare
query. Attachingcountry,seniority, or anything else costs nothing and sharply narrows the result set. A query-only call is the least precise shape available and no cheaper than a filtered one.Drop
queryentirely when filters can carry the whole intent. “VPs of sales at US software companies” is fully expressible asseniority,department,industry, andcountry— as a pure filter search it runs ~40× cheaper than the same request phrased as free text.
This is about execution cost, not billing. Tokens are charged per record returned regardless of query shape — a cheaper query returns faster and puts less load on search capacity, but it doesn’t change what you’re charged.
If all you have is text, add a country
country is ~99% filled — the highest fill rate of any filter. Attaching it to a free-text search discards almost no legitimate matches while removing everything from other markets. It is the cheapest precision available, and the default filter to reach for when you have nothing else.
{ "query": "Account Executive", "country": "United States" }
Put the right thing in query
query is a full-text search across full_name, first_name, last_name, company name, title (~85% filled), and headline (~65% filled). Multi-word queries distribute terms across fields — "John Smith" matches first_name: John and last_name: Smith rather than either alone.
Put this in | Use a dedicated filter instead |
Names — | Country, state, city |
Role and function keywords — | Seniority level ( |
Headline phrases — | Industry, department, company size, revenue |
Naming a company in query gets it diluted across the name and title fields. Use company or company_domain to scope to an employer.
Know each filter’s fill rate
Every exact-match filter silently discards records where that field is empty. Stacking three sparse filters can cut a viable audience to nothing.
Filter | Fill rate | Notes |
| ~99% | The most reliable filter available |
| ~85% |
|
| ~65% |
|
| ~60% |
|
| ~60% |
|
| ~60% | Co-populated — use one or the other, never both |
| ~50% |
|
| ~50% |
|
department and functional_area share the same underlying data, the same document counts, and the same values. Filtering on both narrows nothing and risks contradicting yourself — pick one.
Choose your industry granularity
Three filters describe industry at different resolutions. Pick the one that matches how specific your targeting actually is.
Filter | Vocabulary | Use when |
| 21 broad buckets | You’re thinking in categories like “software” or “healthcare” |
| LinkedIn’s own ~150 labels | You need a niche the broad buckets can’t express — |
| Full NAICS hierarchy | You need standardised codes, or want to control breadth precisely |
naics_code works at any level of the hierarchy. A 2-digit sector is broad ("54"= Professional Services); a 6-digit code is surgical ("541120"= Offices of Notaries). Shorten the code to widen the net. See Understanding NAICS Codes for more information.
Get location right
country, state, and city all filter theperson’slocation and all require exact stored values.
Use full English names, not abbreviations —
"Texas", not"TX"."UK"and"HK"exist in the data as dirty values. Prefer"United Kingdom"and"Hong Kong".City names repeat across regions. Combine with
stateorcountryto disambiguate —city: "Portland",state: "Oregon".citymatches the exact stored city, not its suburbs. For metro-area coverage, filter onstateorcountryinstead.
Target by company size without naming a company
employee_range and revenue_range on search_people filter on the person’s current employer. This finds people at companies of a given size or revenue without you having to supply a company at all.
{ "seniority": "VP", "employee_range": "51-200", "country": "United States" }Both use the same vocabulary as search_companies. Legacy values ("Small", "Mid-Market", "Enterprise", "Unknown") exist but have far thinner coverage — prefer the numeric ranges.
Match exact strings exactly
Every non-query filter is an exact match. The most common failure is a near-miss on capitalisation or spacing:
"C Suite"has a space, not a hyphen"Marketing & Advertising"uses an ampersand"Medical & Health"uses an ampersand"5001+"and"$500k - $1M"must match character for character
Emails come back in the search
search_people results already include business_email and its business_email_risk_score. For contacts where the search returns an email, you don’t need a follow-up enrichment call. See Understanding Email Risk Scores for more information.
Paginate deliberately
Results are ranked — a higher _score means a stronger match, so the first page is the best page.
| Limit |
Results per call | 25 max, 10 default |
Results per call (Free plan) | 5 max |
Free plan lifetime search records | 100 |
Every response carries results.total, the count of matching records across all pages. Read it before paginating to decide whether the search is worth walking, then increment offset by your limit.