Lead Search API and MCP: Build B2B Lists From Filters, Not Exports

A b2b lead search api takes filters, such as job title, seniority, location, company size, tech stack and funding, and returns the people who match as structured data, so a prospect list is something your code builds on demand rather than a CSV exported last quarter. NeuralVerge's leads search does this with one request and bills 2 points per returned record, over REST or MCP.

The short version

• —What it is: a search that turns a description of the people you want into a list of them, one page at a time. It finds who; it does not give you their email or phone.
• —Who it is for: teams building outbound lists, mapping accounts, planning territories or shortlisting candidates, and agents that need a list on request.
• —What it costs: 2 points per returned record. A page of 10 is 20 points, a page of 25 is 50 points. On the Base plan ($50 for 50,000 points a month) that is about $2 per 1,000 records.
• —What to watch: the level and country filters behave in specific ways, shown below with a real response. Read a small page before you scale up.

From filters to a list

A lead is a person at a company, with enough role and company context to decide whether to contact them. The workflow has four steps, and the order matters because the cheap, wide step comes before the expensive, narrow one. Unlike a list export, which starts aging the moment it is saved, a search is a request: keep the filter definition rather than the file, and re-run it when you need a fresh list.

1. Describe the list

Pick the filters that define your target and start narrow. The documented filters fall into four groups, and every one is optional:

• —The person: include and exclude job titles, seniority level (for example C-level, VP, Director), department, skills, languages and headline keywords.
• —Where they are: continent, country, state and city for the person, plus a separate headquarters country, state and city for the company.
• —The company: name, domain include and exclude lists, industry by LinkedIn, NAICS or SIC classification, revenue band, employee count range and keywords.
• —Signals: technology in use (CRM, cloud provider, analytics, e-commerce platform, ERP and more), funding, traffic, open roles, LinkedIn growth, ad spend and flags such as having a CISO.

Most useful lists are a role plus a reason: a Director of Engineering at a company on a specific cloud provider. A search with no filters is valid, and the quickest way to spend points on records you will never use. You can also scope the search to one company, which turns it into a way of mapping the people inside an account.

2. Set a page size and run it

Pages hold 10 to 100 leads, 25 by default. A small first page is a cheap way to check that your filters mean what you think. The search runs when you send it.

3. Page through the rest

The page parameter accepts values up to 500,000. In practice you stop long before that.

4. Decide who goes forward

Only then spend points on contact details, for the leads you want. Search finds who; enrichment finds how to reach them. Our explainer on B2B data from one key shows how leads, employees, emails and phones fit together. The narrower LinkedIn people search source filters on profile attributes only, while leads search also filters on the company side, which is the part most targeting depends on.

A B2B lead search API call, with the real response

This is a real call, made on 2026-10-29 against the live MCP tool run_leads_search. It asks for directors and VPs with engineering titles, based in Finland, at companies whose technology profile includes AWS. The page size is 10, the smallest the source accepts.

{
  "tool": "run_leads_search",
  "arguments": {
    "include_title": ["Engineering"],
    "job_levels": ["Director", "VP"],
    "country": ["Finland"],
    "cloud_provider": ["AWS"],
    "page": 1,
    "page_size": 10
  }
}

Two things are changed for publication. The records are real people, so personal identifiers (full name, first name, last name, headline and LinkedIn URL) are replaced with "[redacted]". And the response held 10 records, of which we show two; each line containing only ... stands for the eight we left out, so the block is not valid JSON as printed. Everything else is verbatim.

{
  "session_id": "4e1702ca-0459-4e28-b245-6e563014abf2",
  "kind": "leads_search",
  "company_linkedin_url": "",
  "filters": {
    "jobTitle": ["Engineering"],
    "jobLevel": ["Director", "VP"],
    "countryName": ["Finland"],
    "cloudProviderTechOrg": ["AWS"]
  },
  "exclude_filters": {},
  "page": 1,
  "page_size": 10,
  "human": "# Leads search\n\n- **Company:** any\n- **Job title:** Engineering\n- **Seniority level:** Director, VP\n- **Country:** Finland\n- **Cloud provider:** AWS\n- **Page:** 1 (up to 10 per page)\n- **Total matching:** 97\n- **Total pages:** 10\n- **Records returned:** 10",
  "machine": {
    "page": 1,
    "total_pages": 10,
    "total_results": 97,
    "has_more": true,
    "total_items": 10,
    "items": [
      ...
      {
        "ranking": 4,
        "full_name": "[redacted]",
        "first_name": "[redacted]",
        "last_name": "[redacted]",
        "headline": "[redacted]",
        "linkedin_url": "[redacted]",
        "location": "Finland",
        "city": null,
        "state": null,
        "country": "Finland",
        "email_domain": "finnair.com",
        "job_title": "Head of Engineering Services",
        "job_level": "Director",
        "job_function": "Engineering",
        "skills": ["airworthiness", "flight safety", "flights", "aircraft", "airlines", "flight test", "civil aviation", "engineering", "aerospace", "aviation", "aircraft maintenance", "avionics", "aeronautics"],
        "company": "Finnair",
        "company_linkedin_url": "https://www.linkedin.com/company/finnair",
        "company_domain": "finnair.com",
        "company_employee_count": 4222,
        "company_industry": "Scheduled Passenger Air Transportation;Other Nonscheduled Air Transportation;Other Airport Operations",
        "company_revenue": "$50M to <$100M",
        "company_founded_on": "1923",
        "company_hq": "Vantaa, Uusimaa, Finland",
        "company_total_funding": 0,
        "company_last_funding_type": "Post-IPO Debt",
        "company_last_funding_date": "2026-01-30",
        "company_monthly_traffic": 32243,
        "company_linkedin_growth_rate": 1
      },
      {
        "ranking": 5,
        "full_name": "[redacted]",
        "first_name": "[redacted]",
        "last_name": "[redacted]",
        "headline": "[redacted]",
        "linkedin_url": "[redacted]",
        "location": "Espoo, Finland",
        "city": "Espoo",
        "state": null,
        "country": "Finland",
        "email_domain": "neste.com",
        "job_title": "Head of Engineering",
        "job_level": "Director",
        "job_function": "Engineering",
        "skills": [],
        "company": "Neste",
        "company_linkedin_url": "https://www.linkedin.com/company/neste",
        "company_domain": "neste.com",
        "company_employee_count": 4536,
        "company_industry": "All Other Business Support Services;All Other Professional; Scientific; and Technical Services;Other Management Consulting Services",
        "company_revenue": "$1B+",
        "company_founded_on": "1948",
        "company_hq": "Espoo, Uusimaa, Finland",
        "company_total_funding": 0,
        "company_last_funding_type": "Grant",
        "company_last_funding_date": "2026-01-30",
        "company_monthly_traffic": 7034,
        "company_linkedin_growth_rate": 0
      },
      ...
    ]
  },
  "total_points": 20
}

The cost is on the last line: total_points is 20, which is 10 returned records at 2 points each.

Reading the envelope

• —total_results is 97. That is how many people match this filter set, spread over total_pages of 10 at 10 per page. The page we asked for returned 10 records (total_items), and has_more is true.
• —filters echoes your request under different key names. We sent include_title, job_levels, country and cloud_provider; the echo says jobTitle, jobLevel, countryName and cloudProviderTechOrg.
• —human is a readable summary of the same search, useful when an agent needs to tell a person what it just ran. The records are under machine, and ranking is the position on the page (the two shown are 4 and 5).

What a record holds

These are the fields that appear in the captured records, grouped by what they describe.

The records include no email address or phone number, only the email_domain hint. The cloud_provider filter is not repeated in the record, so you cannot read "uses AWS" off the lead afterwards.

REST and MCP

The same leads search is reachable two ways. Over MCP, a connected agent such as Claude calls the tool run_leads_search directly and fills in the filters from a plain-English request; the call above is exactly that. Over REST, you send the same filters from your own code.

We do not show a REST URL in this post, because none is published in its source material. Take the request shape and the accepted value for each filter from docs.neuralverge.ai before you build on it, and see the MCP setup guide to connect a client.

If an agent runs the search, the risk is a vague request that returns a large page. Give it a points budget, have it start with 10 records, and have it report total_results back before it pages further.

Check the data before acting

Ten records are a small sample, but they show patterns any list built from public profiles and company data will contain.

The level filter is a label, not a guarantee

Both records shown carry job_level "Director". Their titles are "Head of Engineering Services" and "Head of Engineering", which are plausible directors. Across the full ten, "Director" was also assigned to titles of quite different seniority, including one beginning with "Expert". The level is a label derived from the title, so read job_title too.

The country filter matches the person, not the company

We asked for Finland and got 97 matches, but several of the ten work for companies headquartered elsewhere, including Aberdeen, Santa Clara, Hyderabad and New York. The filter matched where the person is located. If you want Finnish companies, filter on the headquarters country too, or check company_hq.

Some company fields are placeholders

In the records shown, company_total_funding is 0 for both companies, and elsewhere in the ten we saw company_founded_on as "0" and a null company_revenue. Treat 0 and "0" as unknown, not as a fact. company_linkedin_growth_rate is 1 on one record and 0 on the other; a 0 may mean no growth or nothing measured. Other details deserve a sanity check rather than trust:

• —The first company's revenue band reads $50M to <$100M next to a headcount of 4,222, so the band looks like an estimate. Use it to rough-sort, not to qualify.
• —Both records show the same company_last_funding_date, 2026-01-30, with different funding types. Check before you build a "recently funded" rule on it.
• —skills can be empty and city and state can be null. country was filled in on both.

The industry field is a joined string

company_industry is a single string with labels joined by semicolons, but a label can contain semicolons itself: the second record includes "All Other Professional; Scientific; and Technical Services", which is one label. Splitting on ; cuts it into pieces, so treat the field as text or match known labels against it.

A worked example (illustrative)

Acme Oy, a made-up software company in Finland, sells a monitoring product to teams on a particular cloud provider. Its sales lead runs a first page of 10 leads (20 points), sees two titles she did not mean, adds an exclude-title filter and runs again. She walks a few pages, drops the leads who clearly do not fit, and passes the name and company domain of the rest to the email finder, a separate lookup with its own price. None of this is a number from a real run; it shows the order of operations.

Cost and limits

Leads search is billed at 2 points for each returned record. The real call above returned 10 records and reported total_points of 20. A page of 25, the default, is 50 points; a page of 100 is 200 points. Walking all 97 matches would come to 194 points against 20 for the first page; that is arithmetic, not a measured run.

On the Base plan ($50 for 50,000 points a month) a point is a tenth of a cent, so 2 points per record is about $2 per 1,000 records. That is a conversion from the plan page, not a separate price list; check the pricing page for current terms.

You pay for records returned, so precision saves money: a tight filter costs less than a loose one you must sift. The source does not state what happens to a search that matches nothing, so we will not either; run a small test if it matters to your budget.

Limits

• —Results reflect what people publish. Titles, skills and locations are as accurate as the profiles they come from, and company signals are inferred from outside.
• —Page limits are interface limits. Neither 100 per page nor 500,000 pages says anything about how many people match a search.
• —Personal data rules apply. A lead is a person, and where you operate, privacy and marketing rules decide how you may contact them.
• —No contact details. You need a second step for email or phone.

How to decide

1. —Do you need a list you can rebuild on demand? Outbound prospecting, account mapping, territory planning and recruiting shortlists all fit: keep the filters, not the file.
2. —Run a 10-lead page and read every field. Check that the fields you need are present and the filters behave as named.
3. —Compare each filter with its field. Does the country filter match the person or the company? Does the level label match the title?
4. —Check the filter vocabulary against your CRM. Unmappable seniority and industry labels cost engineering time.
5. —Ask what a record costs and when you are charged. Here it is per returned record, and contact details are a separate step you pay for only on the leads you keep.
6. —Will an agent run it? Give it a page size and a budget it cannot exceed.
7. —Re-run it a week later. A search is only as good as its repeatability.

Frequently asked questions

How much does a lead search cost?

Leads search is priced at 2 points per returned record. A page of 25 leads is therefore 50 points. On the Base plan, which includes 50,000 points a month for $50, that works out to about $2 per 1,000 records. Check the pricing page for current plan terms.

Does lead search return email addresses and phone numbers?

No. A record holds name, job title, seniority level, job function, location, LinkedIn profile, skills, an email domain and company details, but no email address or phone number. Contact details are a separate step: take the name and company domain to the email finder source, or the profile to a phone or email enrichment source, and pay for that lookup only on the leads you keep.

How many leads can one search return?

Results are paged. A page holds between 10 and 100 leads (25 by default), and the page parameter accepts values up to 500,000. That is a limit on the interface, not a statement about how many people match any given filter. In our captured run, 97 people matched and the first page of 10 was one of 10 pages. Narrow filters return shorter lists.

Does the country filter match the person or the company?

The person. In our captured run, a search for Finland returned people located in Finland, several of whom work for companies headquartered elsewhere. If you want Finnish companies, also filter on the company headquarters country or check the company_hq field on each record.

Can I use lead search from an AI agent or over MCP?

Yes. The same search is available over MCP as a tool named run_leads_search, with the same filters as arguments, and over REST. An agent can translate a plain-English request into filters and call it. Because each returned record costs points, give the agent a page size and a budget.

Is this a database I download?

No. You send filters and get back the matching leads for that request, a page at a time. There is no bulk export to manage, and you pay for the records you ask for rather than for a seat or a file.