Introducing the ScrapingBee Agentic Employee Search API

The ScrapingBee Agentic Employee Search API lets you find relevant employee profiles using natural-language queries.

Instead of building complex filters or searching profiles manually, you describe the people you’re looking for — for example, senior data scientists at large tech companies in the US — and the API returns matching profiles as structured JSON.

You can search by role, seniority, industry, company characteristics, location, skills, and other signals. In this post, we’ll look at how the API works, how to make your first request, and how to write prompts that return useful results.

Why employee search is a pain

We get it: searching for the right people can turn into a lot of manual work surprisingly fast.

You start with a role, then add seniority, location, industry, company size, maybe a few skills — and suddenly you’re juggling filters, checking profiles one by one, and trying to figure out whether the results actually match what you had in mind.

The Employee Search API cuts out most of that work. You describe the kind of person you’re looking for in plain language, and the API handles the search and ranking for you.

How the Employee Search API works

The Employee Search API takes a natural-language description of the people you want to find and turns it into a search.

You describe the target in plain language — for example, senior backend engineers at fintech companies in Germany — and ScrapingBee finds relevant profiles based on those criteria and ranks them by relevance.

At a high level, the flow looks like this:

Natural-language prompt → Employee Search API → ranked employee profiles

You don’t need to build a complex filter system yourself or manually combine multiple search criteria.

Quickstart: search for employees with Python

To make your first search, you need a ScrapingBee API key and a natural-language description of the people you want to find.

Install the requests package if you don’t already have it:

pip install requests

For example, let’s search for senior machine learning engineers living in Austin and working at fintech companies, and limit the response to five profiles:

import requests

API_KEY = "YOUR API KEY"

response = requests.get(
    "https://app.scrapingbee.com/api/v1/agentic_search",
    headers={
        "Authorization": f"Bearer {API_KEY}",
    },
    params={
        "prompt": "Senior machine learning engineers living in Austin, Texas, working at fintech companies",
        "limit": 5,
    },
)

response.raise_for_status()

data = response.json()

for profile in data["results"]:
    print(profile.get("full_name"))
    print(profile.get("active_experience_title"))
    print(profile.get("company_name"))
    print(profile.get("location_full"))
    print(profile.get("linkedin_url"))
    print()

The prompt describes the people you want to find, while limit controls the maximum number of profiles returned.

Here's the sample output:

John Doe
Senior Machine Learning Engineer
Company 1
Austin, Texas Metropolitan Area
https://www.linkedin.com/in/sample

Jane Doe
Senior Machine Learning Engineer
Company 2
Austin, Texas, United States
https://www.linkedin.com/in/demo

ScrapingBee runs the search and returns matching profiles as structured JSON, ranked by relevance.

Understanding the response

The API returns a JSON object with the original prompt, the requested result limit, the number of profiles found, and a results array.

A shortened response might look like this:

{
  "limit": 2,
  "prompt": "Senior machine learning engineers living in Austin, Texas, working at fintech companies",
  "result_count": 2,
  "results": [
    {
      "id": 123456789,
      "full_name": "Alex Morgan",
      "headline": "Senior Machine Learning Engineer",
      "linkedin_url": "https://www.linkedin.com/in/alex-morgan-example",
      "location_full": "Austin, Texas, United States",
      "location_country": "United States",
      "active_experience_title": "Senior Machine Learning Engineer",
      "active_experience_department": "Engineering and Technical",
      "active_experience_management_level": "Senior",
      "company_name": "ExamplePay",
      "company_industry": "Financial Services",
      "company_website": "https://examplepay.com",
      "company_linkedin_url": "https://www.linkedin.com/company/examplepay",
      "company_hq_country": "United States",
      "company_hq_full_address": "100 Market Street, San Francisco, California, US",
      "connections_count": 500,
      "followers_count": 820
    },
    {
      "id": 987654321,
      "full_name": "Jordan Lee",
      "headline": "Principal ML Engineer",
      "linkedin_url": "https://www.linkedin.com/in/jordan-lee-example",
      "location_full": "Austin, Texas Metropolitan Area",
      "location_country": "United States",
      "active_experience_title": "Principal Machine Learning Engineer",
      "active_experience_department": "Engineering and Technical",
      "active_experience_management_level": "Senior",
      "company_name": "Fintech Labs",
      "company_industry": "Software Development",
      "company_website": "https://fintechlabs.example",
      "company_linkedin_url": "https://www.linkedin.com/company/fintechlabs-example",
      "company_hq_country": "United States",
      "company_hq_full_address": "500 Congress Avenue, Austin, Texas, US",
      "connections_count": 340,
      "followers_count": 410
    }
  ]
}

The top-level fields describe the search itself:

• prompt — the natural-language query you sent.
• limit — the maximum number of profiles requested.
• result_count — the number of profiles returned.
• results — the matching employee profiles. If no matching profiles are found, results is an empty array. This is a valid response, not an error, and the request is not charged.

Each profile contains information about the person, their current role, their employer, and their location. For example, active_experience_title contains the current job title, while company_name and company_industry describe the employer.

The search is relevance-based rather than a strict field-by-field filter. For example, a search for senior engineers may also return a principal engineer if the profile is considered a strong match.

Employee Search API parameters

The Employee Search API uses a single GET endpoint:

https://app.scrapingbee.com/api/v1/agentic_search

You authenticate with your ScrapingBee API key and pass the search options as query parameters.

prompt

The prompt parameter is required. It contains the natural-language description of the employees you want to find and can be up to 5,000 characters long.

params = {
    "prompt": "Senior machine learning engineers living in Austin, Texas, working at fintech companies"
}

We’ll look at how to write effective prompts in the next section.

limit

The optional limit parameter controls the maximum number of profiles returned:

params = {
    "prompt": "Senior machine learning engineers living in Austin, Texas, working at fintech companies",
    "limit": 5,
}

It accepts values from 1 to 100. If you omit it, the default is 100.

The actual number of results can be lower than the requested limit if fewer matching profiles are found.

tag

The optional tag parameter lets you attach your own identifier to a request:

params = {
    "prompt": "Senior machine learning engineers living in Austin, Texas, working at fintech companies",
    "limit": 5,
    "tag": "austin-ml-search",
}

ScrapingBee returns the tag with the response headers. It does not change the search itself.

Authentication

Pass your ScrapingBee API key in the Authorization header:

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

Authentication is required for every Employee Search API request.

Tips for writing effective search prompts

The Employee Search API works best when the prompt is specific enough to describe the target, but not overloaded with requirements.

A few practical tips:

• Focus on two or three important signals. Start with the role and seniority, then add one important signal such as company type or location.
• Describe what you mean in plain language. For example, senior backend engineers at SaaS companies in Germany is usually better than trying to imitate a complex filter query.
• Be explicit about location. If you care where the person lives, use wording such as living in or based in. Company headquarters and employee location are separate signals.
• Prefer company characteristics over exact employer names. Searching for a specific named company is not reliably supported during the beta. Instead, describe the company by industry, size, or stage, for example fintech companies, Series B startups, or companies with more than 10,000 employees.
• Avoid relying on negative conditions. Prompts such as engineers who are not managers or people not working in finance may not be interpreted consistently.
• Treat the results as relevance matches, not exact database filters. A search for senior machine learning engineers may also return a principal engineer if the profile is otherwise a strong match.
• Start broad, then refine. If a search returns no results, remove one condition or make the wording less restrictive before adding more criteria. If you need more precision, consider running a second search with a different angle instead of stacking many requirements into one prompt.
• Capitalization, minor typos, and non-English prompts are supported. You can also write the prompt as a normal question rather than a keyword list.

The API can also search using signals such as skills, company size, recent job changes, career moves, follower counts, and separate employee and company locations.

Employee Search API pricing

Each successful Employee Search API request that returns at least one matching profile costs 3,750 ScrapingBee API credits.

Requests that return no matching profiles are free. Failed requests are also not charged; ScrapingBee automatically retries them up to three times before returning an error.

The monetary cost depends on your ScrapingBee plan and the number of API credits included with it.

Get started with the Employee Search API

The Employee Search API gives you a simple way to find relevant employee profiles from a natural-language description, without building your own search and filtering system.

For the full list of parameters, response fields, prompt examples, and current limitations, check the Employee Search API documentation.

If you want to get started, create a free ScrapingBee account and start exploring the API today.

FAQ

What is an Agentic Employee Search API?

An Agentic Employee Search API lets you find relevant employee profiles programmatically. With ScrapingBee, you describe the people you are looking for in natural language and receive matching profiles as structured JSON.

What can I search for with the Agentic Employee Search API?

You can search by signals such as job title, seniority, skills, industry, company characteristics, and location. You can also combine several criteria in the same prompt.

Does the Agentic Employee Search API use exact filters?

Not necessarily. The API ranks profiles by relevance rather than applying every part of the prompt as a strict database filter. For example, a search for senior engineers may also return a principal engineer if the profile is considered a strong match.

How much does the Agentic Employee Search API cost?

A request that returns at least one result costs 3,750 ScrapingBee API credits. Requests that return no results and failed requests are not charged.