# Agentic Search API
The Coresignal Agentic Search API is a natural language search API for querying professional data. Instead of writing structured queries, you describe what you need in natural language, and the API handles the rest.
Built for agentic workflows, LLM pipelines, and AI-powered applications, it eliminates the need to manually construct Elasticsearch queries. Whether you are enriching leads, building a recruitment tool, or powering an AI agent with business data, Agentic Search API gives you a faster path from prompt to data.
Depending on your use case, there are several response methods available:
| |
|---|
| Elasticsearch DSL query | Receive a generated Elasticsearch query to run yourself via multi-source API. Useful when you need control over execution or want to inspect query logic. |
| Data preview | Receive matching data records directly in a single response – results are ready to use immediately. |
## Endpoints
| Endpoint | Description | Best for |
| ------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `/v2/agentic_search/fast` | Natural language prompts quickly and cheaply translate it into a request. | High-volume, programmatic use cases, powering AI agents, search features in your products, or automated pipelines. |
## Request body
Discover request body parameters. Only `prompt` is required and the remaining parameters let you control what is returned and how many results to include.
| Parameter | Type | Required | Default | Description |
|---|
prompt | String | Required | – | Natural language query describing the employees you want to find. |
return_data | Boolean | Optional | false | When false, returns an Elasticsearch DSL query. When true, returns preview data. |
limit | Integer | Optional | 20 | Max results to return when return_data is true. Range: 1–100. |
entity | String | Optional | "employee" | Target entity type. Currently only "employee" is supported. |
### Prompt examples
Here are a few examples of prompts that can be used for your projects.
> Find founders or co-founders who have previously held an engineering role at Google, Meta, Apple, Amazon, or Microsoft.
> Find VPs of Sales or Chief Revenue Officers who previously worked at Salesforce or HubSpot.
> Find heads of engineering or CTOs at European fintech companies who have US work experience.
## Output modes
The `return_data` parameter controls what is returned. Choose between a generated query for your own pipeline or receiving data directly.
| |
|---|
| Query mode | return_data: false (default)
Returns the generated Elasticsearch DSL query. Use this to integrate it into your own requests or to inspect the generated query logic. |
| Data mode | return_data: true
Executes the query and returns preview data results directly. Up to 100 results delivered in a single response. |
### Query output `return_data: false`
The endpoint with `return_data: false` parameter generates an Elasticsearch DSL query from your natural language prompt and returns it. The query can then be submitted independently to multi-source endpoint accordingly. The Elasticsearch DSL query is not executed in this mode.
#### Example request
```json
// Find senior engineers at fintech companies in New York
curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/agentic_search/fast' \
-H 'accept: application/json' \
-H 'apikey: {API key}' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "Find heads of engineering or CTOs at European fintech companies who have US work experience.",
"return_data": false,
"entity": "employee"
}
```
{% hint style="success" %}
Get your API Key from Coresignal's [self-service platform](https://dashboard.coresignal.com/sign-in).
{% endhint %}
#### Example response
{% code expandable="true" %}
```json
{
"query": {
"bool": {
"filter": [
{
"term": {
"is_deleted": 0
}
},
{
"term": {
"is_parent": 1
}
}
],
"must": [
{
"nested": {
"path": "experience",
"query": {
"bool": {
"filter": [
{
"term": {
"experience.active_experience": 1
}
},
{
"match_phrase": {
"experience.company_hq_regions": "Europe"
}
}
],
"must": [
{
"bool": {
"should": [
{
"match_phrase": {
"experience.position_title": "Head of Engineering"
}
},
{
"match_phrase": {
"experience.position_title": "CTO"
}
},
{
"match_phrase": {
"experience.position_title": "Chief Technology Officer"
}
}
],
"minimum_should_match": 1
}
},
{
"bool": {
"should": [
{
"match": {
"experience.company_categories_and_keywords": {
"query": "fintech",
"operator": "and"
}
}
},
{
"terms": {
"experience.company_industry.exact": [
"Banking"
]
}
}
],
"minimum_should_match": 1
}
}
]
}
}
}
},
{
"nested": {
"path": "experience",
"query": {
"bool": {
"filter": [
{
"term": {
"experience.active_experience": 0
}
},
{
"terms": {
"experience.company_hq_country_iso2": [
"US"
]
}
}
]
}
}
}
}
]
}
},
"sort": [
"_score"
]
}
```
{% endcode %}
### Data output `return_data: true`
The endpoint with `return_data: true` parameter generates the Elasticsearch DSL query internally, executes it, and returns results directly. The Elasticsearch DSL query is not exposed in this mode.
The `limit` parameter available on this mode controls the maximum number of results returned. Default value is `20`, and maximum is `100`.
#### Response structure
Here is an overview of the fields that are included in the response.
| Data field | Description | Data type |
| ------------------------------------ | -------------------------------------------------------- | --------- |
| `id` | Identification number | Integer |
| `full_name` | Employee's full name | String |
| `professional_network_url` | Most recent profile URL | String |
| `headline` | Profile headline | String |
| `location_full` | Employee's full location | String |
| `location_country` | Associated country | String |
| `connections_count` | Count of profile connections | Integer |
| `followers_count` | Count of profile followers | Integer |
| `company_name` | Company name | String |
| `company_professional_network_url` | Company's profile URL | String |
| `company_website` | Company's website | String |
| `company_industry` | Company's industry | String |
| `active_experience_title` | Title of employee's current position | String |
| `active_experience_department` | A list of employee's departments | String |
| `active_experience_management_level` | A list of employee's management levels | String |
| `company_hq_full_address` | Full address of the company's headquarters | String |
| `company_hq_country` | The country where the company's headquarters are located | String |
| `_score` | Elasticsearch DSL score | Float |
#### Example request
```json
curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/agentic_search/fast' \
-H 'accept: application/json' \
-H 'apikey: {API key}' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "Find founders or co-founders who have previously held an engineering role at Google, Meta, Apple, Amazon, or Microsoft.",
"return_data": true,
"limit": 1,
"entity": "employee"
}
```
{% hint style="success" %}
Get your API Key from Coresignal's [self-service platform](https://dashboard.coresignal.com/sign-in).
{% endhint %}
#### Example response
{% code expandable="true" %}
```json
[
{
"id": 123456789,
"full_name": "John Doe",
"professional_network_url": "https://www.professional-network.com/john-doe",
"headline": "Product Development",
"location_full": "Redmond, Washington, United States",
"location_country": "United States",
"connections_count": 500,
"followers_count": 12345,
"company_name": "Example Company",
"company_professional_network_url": "https://www.professional-network.com/company/example-company",
"company_website": "https://www.example-company.com",
"company_industry": "Technology, Information and Internet",
"active_experience_title": "Co-Founder",
"active_experience_department": "Consulting",
"active_experience_management_level": "Founder",
"company_hq_full_address": "1 Fake st; Redmond, Washington 00000, US",
"company_hq_country": "United States",
"_score": 20.123123
}
]
```
{% endcode %}
## Pricing
Search credits are consumed per request. The cost depends on the output mode and, when returning data, on the number of results returned.
| Output mode | Response | Search credits cost |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `return_data: false` | Elasticsearch DSL query | 2 |
| `return_data: true` | 1–20 results returned
21–40 results returned
41–60 results returned
61–80 results returned
81–100 results returned
| 2
4
6
8
10
|
{% hint style="info" %}
Credits are charged based on the number of results actually returned, not the value of `limit`. If your query matches fewer results than requested, you are charged for the actual result count.
{% endhint %}
## Response codes
| Response code | Description |
| ------------- | ----------------------------------------------------------------------- |
| `200` | A successful request |
| `400` | Invalid request payload |
| `401` | No valid API Key was provided. Check if your key is valid and try again |
| `402` | Insufficient credits. Add more credits to continue |
| `502` / `503` | Engine timeout / upstream error |