Documentation

Agentic Employee Search API

Select a language:

Overview

Here is the list of the different parameters you can use with ScrapingBee's Agentic Employee Search API.

You can also discover this API using our Postman collection covering every ScrapingBee's features.

Our Agentic Employee Search API lets you describe the people you want to find in plain language and returns structured employee profiles in realtime.

We provide one endpoint:

  • Agentic Employee Search endpoint (/api/v1/agentic_search): Send a natural-language prompt and receive matching employee profiles

Quick start

To use the Agentic Employee Search API, you only need two things:

Then, simply do this.

Copy
curl "https://app.scrapingbee.com/api/v1/agentic_search?limit=10&prompt=senior+data+scientists+at+large+tech+companies+in+the+US" \
     -H "Authorization: Bearer YOUR-API-KEY"

#  Install the Python Requests library:
# pip install requests
import requests

def send_request():
    response = requests.get(
        url='https://app.scrapingbee.com/api/v1/agentic_search',
        headers={
            'Authorization': 'Bearer YOUR-API-KEY',
        },
        params={
            'limit': '10',
            'prompt': 'senior data scientists at large tech companies in the US',
        },

    )
    print('Response HTTP Status Code: ', response.status_code)
    print('Response HTTP Response Body: ', response.content)
send_request()

// Install the Node Axios package
// npm install axios
const axios = require('axios');

axios.get('https://app.scrapingbee.com/api/v1/agentic_search', {
    headers: {
        'Authorization': 'Bearer YOUR-API-KEY',
    },
    params: {
        'limit': '10',
        'prompt': 'senior data scientists at large tech companies in the US',
    }
}).then(function (response) {
    // handle success
    console.log(response);
})

import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }

  private static void sendRequest() {

    // Classic (GET )
    try {

      // Create request
      
      Content content = Request.Get("https://app.scrapingbee.com/api/v1/agentic_search?limit=10&prompt=senior+data+scientists+at+large+tech+companies+in+the+US")

      // Authenticate with your API key
      .addHeader("Authorization", "Bearer YOUR-API-KEY")

      // Fetch request and return content
      .execute().returnContent();

      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

require 'net/http'
require 'net/https'

# Classic (GET )
def send_request 
    uri = URI('https://app.scrapingbee.com/api/v1/agentic_search?limit=10&prompt=senior+data+scientists+at+large+tech+companies+in+the+US')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    # Create Request
    req =  Net::HTTP::Get.new(uri)
    # Authenticate with your API key
    req['Authorization'] = 'Bearer YOUR-API-KEY'

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{ res.code }"
    puts "Response HTTP Response Body: #{ res.body }"
rescue StandardError => e
    puts "HTTP Request failed (#{ e.message })"
end

send_request()

<?php

// get cURL resource
$ch = curl_init();

// set url 
curl_setopt($ch, CURLOPT_URL, 'https://app.scrapingbee.com/api/v1/agentic_search?limit=10&prompt=senior+data+scientists+at+large+tech+companies+in+the+US');

// authenticate with your API key
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR-API-KEY',
]);

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);



// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
    die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);
>

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func sendClassic() {
	// Create client
	client := &http.Client{}

	// Create request 
	req, err := http.NewRequest("GET", "https://app.scrapingbee.com/api/v1/agentic_search?limit=10&prompt=senior+data+scientists+at+large+tech+companies+in+the+US", nil)

	// Authenticate with your API key
	req.Header.Set("Authorization", "Bearer YOUR-API-KEY")

	parseFormErr := req.ParseForm()
	if parseFormErr != nil {
		fmt.Println(parseFormErr)
	}

	// Fetch Request
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println("Failure : ", err)
	}

	// Read Response Body
	respBody, _ := ioutil.ReadAll(resp.Body)

	// Display Results
	fmt.Println("response Status : ", resp.Status)
	fmt.Println("response Headers : ", resp.Header)
	fmt.Println("response Body : ", string(respBody))
}

func main() {
    sendClassic()
}

# Install the ScrapingBee CLI:
# pip install scrapingbee-cli

scrapingbee scrape --limit 10 --prompt "senior data scientists at large tech companies in the US"

Here is a breakdown of all the parameters you can use with the Agentic Employee Search API:

name [type] (default)
Description
api_key [string] required
Your api key
Learn more
prompt [string] required
The natural-language query describing the people you want to find (up to 5000 characters)
Learn more
limit [integer] (100)
The maximum number of results to return, between 1 and 100
Learn more
tag [string] ("")
A custom identifier to label requests, returned with the response headers.
Learn more

Response Example

The API will then respond with formatted JSON data:

{
    # The prompt you sent, echoed back
    "prompt": "senior data scientists at large tech companies in the US",
    # The limit you requested
    "limit": 10,
    # The number of profiles returned
    "result_count": 1,
    # The matching employee profiles, ordered by relevance
    "results": [
        {
            "id": 123456789,
            "full_name": "John Doe",
            "linkedin_url": "https://www.linkedin.com/in/john-doe",
            "headline": "Senior Data Scientist at Example Analytics",
            "location_full": "San Francisco, California, United States",
            "location_country": "United States",
            "connections_count": 500,
            "followers_count": 12345,
            "company_name": "Example Analytics",
            "company_linkedin_url": "https://www.linkedin.com/company/example-analytics",
            "company_website": "https://www.example.com",
            "company_industry": "Software Development",
            "active_experience_title": "Senior Data Scientist",
            "active_experience_department": "Research",
            "active_experience_management_level": "Senior",
            "company_hq_full_address": "500 Example Street; San Francisco, CA 94105, US",
            "company_hq_country": "United States"
        }
    ]
}

Keep in mind that each successful API call that returns results will cost you 150 api credits. Requests that return no matching results are free, and failed requests are not charged (they are retried automatically, up to 3 attempts).



API key

api_key
[
string
] (
""
)
required

All requests are authenticated by using your private API key.

To get access to your API key, just create an account here and confirm your email.



Prompt

prompt
[
string
] (
""
)
required

The prompt parameter is the natural-language query describing the people you want to find. This is required, and it can be up to 5000 characters long.

Describe the role, seniority, company, industry, and location that matter to you. Keep it to two or three signals — prompts that stack many requirements often return no results.

Example prompts:

  • "senior python engineers at fintech companies in London"
  • "product managers in the healthcare industry in Germany"
Copy
curl "https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+python+engineers+at+fintech+companies+in+London" \
     -H "Authorization: Bearer YOUR-API-KEY"

#  Install the Python Requests library:
# pip install requests
import requests

def send_request():
    response = requests.get(
        url='https://app.scrapingbee.com/api/v1/agentic_search',
        headers={
            'Authorization': 'Bearer YOUR-API-KEY',
        },
        params={
            'prompt': 'senior python engineers at fintech companies in London',
        },

    )
    print('Response HTTP Status Code: ', response.status_code)
    print('Response HTTP Response Body: ', response.content)
send_request()

// Install the Node Axios package
// npm install axios
const axios = require('axios');

axios.get('https://app.scrapingbee.com/api/v1/agentic_search', {
    headers: {
        'Authorization': 'Bearer YOUR-API-KEY',
    },
    params: {
        'prompt': 'senior python engineers at fintech companies in London',
    }
}).then(function (response) {
    // handle success
    console.log(response);
})

import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }

  private static void sendRequest() {

    // Classic (GET )
    try {

      // Create request
      
      Content content = Request.Get("https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+python+engineers+at+fintech+companies+in+London")

      // Authenticate with your API key
      .addHeader("Authorization", "Bearer YOUR-API-KEY")

      // Fetch request and return content
      .execute().returnContent();

      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

require 'net/http'
require 'net/https'

# Classic (GET )
def send_request 
    uri = URI('https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+python+engineers+at+fintech+companies+in+London')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    # Create Request
    req =  Net::HTTP::Get.new(uri)
    # Authenticate with your API key
    req['Authorization'] = 'Bearer YOUR-API-KEY'

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{ res.code }"
    puts "Response HTTP Response Body: #{ res.body }"
rescue StandardError => e
    puts "HTTP Request failed (#{ e.message })"
end

send_request()

<?php

// get cURL resource
$ch = curl_init();

// set url 
curl_setopt($ch, CURLOPT_URL, 'https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+python+engineers+at+fintech+companies+in+London');

// authenticate with your API key
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR-API-KEY',
]);

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);



// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
    die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);
>

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func sendClassic() {
	// Create client
	client := &http.Client{}

	// Create request 
	req, err := http.NewRequest("GET", "https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+python+engineers+at+fintech+companies+in+London", nil)

	// Authenticate with your API key
	req.Header.Set("Authorization", "Bearer YOUR-API-KEY")

	parseFormErr := req.ParseForm()
	if parseFormErr != nil {
		fmt.Println(parseFormErr)
	}

	// Fetch Request
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println("Failure : ", err)
	}

	// Read Response Body
	respBody, _ := ioutil.ReadAll(resp.Body)

	// Display Results
	fmt.Println("response Status : ", resp.Status)
	fmt.Println("response Headers : ", resp.Header)
	fmt.Println("response Body : ", string(respBody))
}

func main() {
    sendClassic()
}

# Install the ScrapingBee CLI:
# pip install scrapingbee-cli

scrapingbee scrape --prompt "senior python engineers at fintech companies in London"

For more examples and guidance on getting the best results, see writing effective prompts.



Limit

limit
[
integer
] (
100
)

The limit parameter controls the maximum number of profiles returned, between 1 and 100. It defaults to 100 if omitted.

Copy
curl "https://app.scrapingbee.com/api/v1/agentic_search?limit=25&prompt=senior+data+scientists+at+large+tech+companies+in+the+US" \
     -H "Authorization: Bearer YOUR-API-KEY"

#  Install the Python Requests library:
# pip install requests
import requests

def send_request():
    response = requests.get(
        url='https://app.scrapingbee.com/api/v1/agentic_search',
        headers={
            'Authorization': 'Bearer YOUR-API-KEY',
        },
        params={
            'limit': '25',
            'prompt': 'senior data scientists at large tech companies in the US',
        },

    )
    print('Response HTTP Status Code: ', response.status_code)
    print('Response HTTP Response Body: ', response.content)
send_request()

// Install the Node Axios package
// npm install axios
const axios = require('axios');

axios.get('https://app.scrapingbee.com/api/v1/agentic_search', {
    headers: {
        'Authorization': 'Bearer YOUR-API-KEY',
    },
    params: {
        'limit': '25',
        'prompt': 'senior data scientists at large tech companies in the US',
    }
}).then(function (response) {
    // handle success
    console.log(response);
})

import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }

  private static void sendRequest() {

    // Classic (GET )
    try {

      // Create request
      
      Content content = Request.Get("https://app.scrapingbee.com/api/v1/agentic_search?limit=25&prompt=senior+data+scientists+at+large+tech+companies+in+the+US")

      // Authenticate with your API key
      .addHeader("Authorization", "Bearer YOUR-API-KEY")

      // Fetch request and return content
      .execute().returnContent();

      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

require 'net/http'
require 'net/https'

# Classic (GET )
def send_request 
    uri = URI('https://app.scrapingbee.com/api/v1/agentic_search?limit=25&prompt=senior+data+scientists+at+large+tech+companies+in+the+US')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    # Create Request
    req =  Net::HTTP::Get.new(uri)
    # Authenticate with your API key
    req['Authorization'] = 'Bearer YOUR-API-KEY'

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{ res.code }"
    puts "Response HTTP Response Body: #{ res.body }"
rescue StandardError => e
    puts "HTTP Request failed (#{ e.message })"
end

send_request()

<?php

// get cURL resource
$ch = curl_init();

// set url 
curl_setopt($ch, CURLOPT_URL, 'https://app.scrapingbee.com/api/v1/agentic_search?limit=25&prompt=senior+data+scientists+at+large+tech+companies+in+the+US');

// authenticate with your API key
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR-API-KEY',
]);

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);



// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
    die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);
>

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func sendClassic() {
	// Create client
	client := &http.Client{}

	// Create request 
	req, err := http.NewRequest("GET", "https://app.scrapingbee.com/api/v1/agentic_search?limit=25&prompt=senior+data+scientists+at+large+tech+companies+in+the+US", nil)

	// Authenticate with your API key
	req.Header.Set("Authorization", "Bearer YOUR-API-KEY")

	parseFormErr := req.ParseForm()
	if parseFormErr != nil {
		fmt.Println(parseFormErr)
	}

	// Fetch Request
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println("Failure : ", err)
	}

	// Read Response Body
	respBody, _ := ioutil.ReadAll(resp.Body)

	// Display Results
	fmt.Println("response Status : ", resp.Status)
	fmt.Println("response Headers : ", resp.Header)
	fmt.Println("response Body : ", string(respBody))
}

func main() {
    sendClassic()
}

# Install the ScrapingBee CLI:
# pip install scrapingbee-cli

scrapingbee scrape --limit 25 --prompt "senior data scientists at large tech companies in the US"


Tag

tag
[
string
] (
""
)

Attach a custom string identifier to any request using the tag parameter. The value will be returned with the response headers. This parameter is optional and has no effect on the search behavior.

Copy
curl "https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+data+scientists+at+large+tech+companies+in+the+US&tag=your+text" \
     -H "Authorization: Bearer YOUR-API-KEY"

#  Install the Python Requests library:
# pip install requests
import requests

def send_request():
    response = requests.get(
        url='https://app.scrapingbee.com/api/v1/agentic_search',
        headers={
            'Authorization': 'Bearer YOUR-API-KEY',
        },
        params={
            'prompt': 'senior data scientists at large tech companies in the US',
            'tag': 'your text',
        },

    )
    print('Response HTTP Status Code: ', response.status_code)
    print('Response HTTP Response Body: ', response.content)
send_request()

// Install the Node Axios package
// npm install axios
const axios = require('axios');

axios.get('https://app.scrapingbee.com/api/v1/agentic_search', {
    headers: {
        'Authorization': 'Bearer YOUR-API-KEY',
    },
    params: {
        'prompt': 'senior data scientists at large tech companies in the US',
        'tag': 'your text',
    }
}).then(function (response) {
    // handle success
    console.log(response);
})

import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }

  private static void sendRequest() {

    // Classic (GET )
    try {

      // Create request
      
      Content content = Request.Get("https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+data+scientists+at+large+tech+companies+in+the+US&tag=your+text")

      // Authenticate with your API key
      .addHeader("Authorization", "Bearer YOUR-API-KEY")

      // Fetch request and return content
      .execute().returnContent();

      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

require 'net/http'
require 'net/https'

# Classic (GET )
def send_request 
    uri = URI('https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+data+scientists+at+large+tech+companies+in+the+US&tag=your+text')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER

    # Create Request
    req =  Net::HTTP::Get.new(uri)
    # Authenticate with your API key
    req['Authorization'] = 'Bearer YOUR-API-KEY'

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{ res.code }"
    puts "Response HTTP Response Body: #{ res.body }"
rescue StandardError => e
    puts "HTTP Request failed (#{ e.message })"
end

send_request()

<?php

// get cURL resource
$ch = curl_init();

// set url 
curl_setopt($ch, CURLOPT_URL, 'https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+data+scientists+at+large+tech+companies+in+the+US&tag=your+text');

// authenticate with your API key
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR-API-KEY',
]);

// set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);



// send the request and save response to $response
$response = curl_exec($ch);

// stop if fails
if (!$response) {
    die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}

echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;

// close curl resource to free up system resources
curl_close($ch);
>

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func sendClassic() {
	// Create client
	client := &http.Client{}

	// Create request 
	req, err := http.NewRequest("GET", "https://app.scrapingbee.com/api/v1/agentic_search?prompt=senior+data+scientists+at+large+tech+companies+in+the+US&tag=your+text", nil)

	// Authenticate with your API key
	req.Header.Set("Authorization", "Bearer YOUR-API-KEY")

	parseFormErr := req.ParseForm()
	if parseFormErr != nil {
		fmt.Println(parseFormErr)
	}

	// Fetch Request
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println("Failure : ", err)
	}

	// Read Response Body
	respBody, _ := ioutil.ReadAll(resp.Body)

	// Display Results
	fmt.Println("response Status : ", resp.Status)
	fmt.Println("response Headers : ", resp.Header)
	fmt.Println("response Body : ", string(respBody))
}

func main() {
    sendClassic()
}

# Install the ScrapingBee CLI:
# pip install scrapingbee-cli

scrapingbee scrape --prompt "senior data scientists at large tech companies in the US" --tag "your text"

Writing effective prompts

The most important rule: use two or three signals, not six. Each additional requirement narrows the search sharply, and highly specific prompts often return no results at all. Start broad, check the results, then add one signal at a time.

  • Name the role and seniority: e.g. "senior backend engineers", "VP of marketing"
  • Add industry, size or stage context: e.g. "at fintech companies", "at Series B startups", "at companies with more than 10,000 employees"
  • Include a location when it matters: e.g. "in Berlin, Germany"
  • Then stop. If you need more precision, run a second, differently-angled search rather than stacking requirements into one prompt.

Prompts can be up to 5000 characters, but length does not improve targeting — only the signals inside them do. Pasting a full job description usually returns nothing, because a typical description contains six or more requirements. Pull out the two or three that matter most.

No results is not an error. An empty results array means the search was too narrow, and it is not charged. Remove your least important requirement and try again.

Targeting a person's location vs. their company's

These are separate signals, and you can use them independently. Be explicit about which one you mean:

  • "engineers living in Portugal" — where the person is
  • "companies headquartered in the United States" — where the employer is

If you combine a strong company requirement with a bare location (e.g. "...at pharmaceutical companies in Switzerland"), the location may be applied to the company rather than to the person. Say "living in" or "based in" when you mean the person.

Phrase requirements positively

Describe who you want, not who you don't. Exclusions such as "who are not in engineering" are not reliably applied, and may return the opposite of what you intended.

Describing companies

Describe companies by industry, size or stage rather than by name — searching for a named employer is not reliably supported during beta.

Widely used shorthand generally works ("Big Four firms", "Fortune 500 companies", "unicorn startups"). If a term returns nothing, describe it plainly instead — "large tech companies" rather than an acronym.

Things you don't need to worry about

Capitalisation, minor typos, and non-English prompts are all handled. Questions ("who are the heads of engineering at logistics startups in Singapore?") work as well as phrases.

More things you can search for

Beyond role, industry and location, the following all work well:

  • Skills — "backend engineers in Poland who work with Kubernetes and Go"
  • Company size — "data analysts at companies with more than 10,000 employees in France"
  • Recency — "engineers in the Netherlands who started a new role in the last six months"
  • Career moves — "product managers in Germany who moved from consulting into technology"
  • Reach — "marketing leaders with over 10,000 LinkedIn followers in Spain"
  • Two locations at once — "software engineers living in Portugal who work for companies headquartered in the United States"
  • Beyond tech — "nurses with critical care certification in Canada"
  • Minimal input — "CTOs in Estonia"

Credit cost for your requests

Each ScrapingBee plan provides a certain amount of API credits per month.

It costs 150 credits per successful Agentic Employee Search API request. Requests that return no results are free, and failed requests are not charged.