> For the complete documentation index, see [llms.txt](https://docs.coresignal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coresignal.com/agentic-search-api/agentic-search-api.md).
# 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. With semantic search applied to job title matching, queries are automatically enriched with synonyms to improve recall.
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 with used Elasticsearch query directly in a single response – results are ready to use immediately. |
## Endpoints
We offer several different API endpoints, each designed for specific use cases and data needs.
{% hint style="success" %}
#### Agentic Search API Playground
Explore the Agentic Search API in our [self-service playground](https://dashboard.coresignal.com/agentic-search-playground). For more details, see the [Agentic Search API Playground](/self-service/features-and-tools/agentic-search-api-playground.md) topic.
{% endhint %}
## `/v2/agentic_search/fast` endpoint
`/v2/agentic_search/fast` is optimized for speed and cost. You specify the entity and provide a natural language prompt, and the endpoint uses a simplified schema to translate it into a query quickly and efficiently. Rate limits vary by [plan](/pricing/pricing.md#compare-monthly-plans), so it's well-suited for high-volume, programmatic workloads, such as powering AI agents, product search features, or automated data 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 data you want to find. |
| `return_data` | Boolean | Optional | `false` | When `false`, returns an Elasticsearch DSL query. When `true`, returns preview data. |
| `entity` | String | Optional | `"employee"` | Target entity type. Accepted values: `employee`, `company`, `job`. |
| `threshold` | Float | Optional | `1` | Set the minimum confidence score for [semantic search](/api-introduction/requests/semantic-search.md). |
### Output modes
The `return_data` parameter controls whether the response includes preview data. In both modes, the response includes the generated Elasticsearch DSL query.
| |
|---|
| Query mode | "return_data": false (default)
Returns the generated Elasticsearch DSL query. Use it to integrate it into your own requests or to inspect the generated query logic. |
| Data mode | "return_data": true
Executes the query and returns the used Elasticsearch query and preview results directly. Up to 20 results are 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**
{% code overflow="wrap" %}
```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"
}'
```
{% endcode %}
{% 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": {
"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"
}
},
{
"terms": {
"experience.management_level.exact": [
"Head",
"C-Level",
"Director"
]
}
}
],
"must": [
{
"bool": {
"must": [
{
"match": {
"experience.company_categories_and_keywords": {
"query": "fintech",
"operator": "and"
}
}
},
{
"terms": {
"experience.company_industry.exact": [
"Financial Services",
"Banking",
"Blockchain Services",
"Software Development",
"Technology, Information and Internet"
]
}
}
]
}
}
]
}
}
}
},
{
"nested": {
"path": "experience",
"query": {
"bool": {
"filter": [
{
"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, executes it, and returns up to 20 results directly. The Elasticsearch DSL query is also returned in this mode.
See the [response structure](#response-structure) below.
**Example request**
{% code overflow="wrap" %}
```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,
"entity": "employee"
}'
```
{% endcode %}
{% hint style="success" %}
Get your API Key from Coresignal's [self-service platform](https://dashboard.coresignal.com/sign-in).
{% endhint %}
**Example response**
{% code overflow="wrap" %}
```json
{
"query": {
"query": {
//Included search query
},
"sort": [
"followers_count"
]
},
"data": [
{
"id": 123456789,
"full_name": "John Doe",
"professional_network_url": "https://www.professional-network.com/john-doe",
"active_experience_title": "Co-Founder",
"active_experience_company_id": 0123456,
"company_name": "Example Company",
"_score": 35.17597,
"followers_count": 2000,
"experience": [
{
"management_level": "Founder",
"company_id": 0123456,
"company_name": "Example Company",
"position_title": "Co-Founder",
"active_experience": 1
}
]
}
]
}
```
{% endcode %}
### How to test
{% stepper %}
{% step %}
#### Get your API key
Log in to the [Coresignal dashboard](https://dashboard.coresignal.com/sign-in) and copy your API key. It is mandatory for your authentication, and you must pass it as the `apikey` header in every request.
{% endstep %}
{% step %}
#### Send your request
Open a terminal and paste the command below, or any other sample request in this article, replacing `{API key}` with your actual key. You can also modify the prompt, entity, or other request parameters to get what you are looking for.
{% code title="" overflow="wrap" %}
```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 software engineers in London with Kubernetes experience.",
"return_data": true,
"entity": "employee"
}'
```
{% endcode %}
{% endstep %}
{% step %}
#### Get data
If everything is set up correctly, you will receive a list of matching records within seconds.
{% endstep %}
{% endstepper %}
## `/v2/agentic_search/reasoning` endpoint
`/v2/agentic_search/reasoning` endpoint is optimized for accuracy on complex, multi-criteria queries. Unlike `/fast`, the `/reasoning` endpoint uses the full data schema, infers entity type automatically from the prompt, and supports all three entity types. It is best suited for exploratory searches, complex multi-agent setups, and use cases where precision matters more than speed.
The endpoint also supports an optional clarification flow. The engine can ask follow-up questions before generating a query, ensuring more accurate results.
`/reasoning` endpoint is subject to rate limits of **10 requests per hour**, making it ideal for high-value, precision-critical queries rather than high-volume workloads.
### 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, or clarification text, when continuing a session. |
session_id | String | Required | – | Required field for sending a request and continuing a clarification session. Must match the session_id returned in the previous clarification response. IDs are in UUID v4 format. |
return_data | Boolean | Optional | false | When false, returns an Elasticsearch DSL query. When true, returns preview data. |
allow_clarification | Boolean | Optional | false | When true, the engine may ask follow-up questions before executing a complex query. |
entity | String | Optional | null | The entity type is automatically determined by the prompt, so this field is optional. |
threshold | Float | Optional | 0.92 | Set the minimum confidence score for semantic search. |
### Prompt interpretation
Since the `/reasoning` endpoint uses semantic search with complete schema and can handle complex requests, it is important to understand how the prompt was translated. Response field `reason` contains an explanation of the returned results – what the engine interpreted from the prompt and why those results were returned. If the prompt is too vague, the `reason` field contains a follow-up question to enable a more precise search and more accurate results.
{% code title="" %}
```json
{
"reason": "I searched for employees based in New York with Python Developer in their current job title, sorted by follower count to surface the most prominent profiles. The search includes various Python Developer title variations to ensure comprehensive results.",
"query": {
...
```
{% endcode %}
### Clarification flow
When `allow_clarification` is `true`, the engine determines whether the prompt is ambiguous and needs more clarification instead of executing the search. Clarifications are returned in the `reason` field and may occur multiple times until the engine has enough context to generate a reliable query. Clarification requests don’t use credits.
{% stepper %}
{% step %}
#### Initial request, clarification triggered
When the engine requires clarification, it returns the following response. The `reason` field contains the clarification questions that should be used to explain the request. You also see a `session_id` which is required for keeping the follow-up request in the same session.
```json
{
"reason": "Please clarify whether you are looking for current or former employees.",
"session_id": "2bf83608-98f4-400b-8724-ec96c5b4141b",
"allow_clarification": true
}
```
{% endstep %}
{% step %}
#### Follow-up clarification request
You need to respond with clarification text in the `prompt` field and use the `session_id` from the previous response. The engine uses session context to resolve the original prompt with the clarification and proceeds to generate the query.
```json
{
"prompt": "I am looking for current employees.",
"session_id": "2bf83608-98f4-400b-8724-ec96c5b4141b",
"return_data": true,
"allow_clarification": true
}
```
{% endstep %}
{% endstepper %}
### Output modes
The `return_data` parameter determines whether the endpoint also retrieves preview data. Both modes return the generated Elasticsearch DSL query, and the output modes match those of the `/fast` endpoint.
| |
|---|
| Query mode | "return_data": false (default)
Returns the generated Elasticsearch DSL query. Use it in your own requests or review the query logic. |
| Data mode | "return_data": true
Returns the generated Elasticsearch DSL query and executes it. The response includes up to 20 matching results. |
#### Query output `return_data: false`
The endpoint with the `"return_data": false` parameter generates an Elasticsearch DSL query from your natural language prompt and returns it. You can then submit this query independently to the multi-source endpoint as needed. The Elasticsearch DSL query is not executed in this mode.
**Example request**
{% code overflow="wrap" %}
```json
// Find senior engineers at fintech companies in New York
curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/agentic_search/reasoning' \
-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.",
"session_id": "2bf83608-98f4-400b-8724-ec96c5b4141b",
"return_data": false,
"allow_clarification": false
}'
```
{% endcode %}
{% 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
{
"reason": "I interpreted 'European fintech companies' as companies in the Financial Services industry headquartered across European countries, and 'heads of engineering or CTOs' as current roles including Head of Engineering, CTO, Chief Technology Officer, and VP Engineering titles. I searched for employees currently in those engineering leadership roles at European fintech companies who also have at least one experience record at a US-based company (any time in their career), sorted by follower count to surface the most prominent profiles.",
"query": {
"sort": [
"followers_count"
],
"query": {
"bool": {
"must": [
{
"nested": {
"path": "experience",
"query": {
"bool": {
"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"
}
},
{
"match_phrase": {
"experience.position_title": "VP Engineering"
}
},
{
"match_phrase": {
"experience.position_title": "VP of Engineering"
}
}
],
"minimum_should_match": 1
}
},
{
"terms": {
"experience.company_hq_country_iso2": [
"AD",
"AL",
"AT",
"BA",
"BE",
"BG",
"BY",
"CH",
"CY",
"CZ",
"DE",
"DK",
"EE",
"ES",
"FI",
"FR",
"GB",
"GR",
"HR",
"HU",
"IE",
"IS",
"IT",
"LI",
"LT",
"LU",
"LV",
"MC",
"MD",
"ME",
"MK",
"MT",
"NL",
"NO",
"PL",
"PT",
"RO",
"RS",
"SE",
"SI",
"SK",
"SM",
"UA",
"VA",
"XK"
]
}
},
{
"match_phrase": {
"experience.company_industry": "Financial Services"
}
},
{
"term": {
"experience.active_experience": 1
}
}
]
}
}
}
},
{
"nested": {
"path": "experience",
"query": {
"terms": {
"experience.company_hq_country_iso2": [
"US"
]
}
}
}
}
],
"filter": [
{
"term": {
"is_deleted": 0
}
},
{
"term": {
"is_parent": 1
}
}
]
}
}
},
"threshold": 0.92
}
```
{% endcode %}
#### Data output `return_data: true`
When the `"return_data": true` parameter is used, the endpoint internally builds and executes the Elasticsearch DSL query, then returns up to 20 results directly. In this mode, the Elasticsearch DSL query is also exposed.
See the [response structure](#response-structure) below.
**Example request**
{% code overflow="wrap" %}
```json
curl -X 'POST' \
'https://api.coresignal.com/cdapi/v2/agentic_search/reasoning' \
-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.",
"session_id": "2bf83608-98f4-400b-8724-ec96c5b4141b",
"return_data": true,
"allow_clarification": false
}'
```
{% endcode %}
{% hint style="success" %}
Get your API Key from Coresignal's [self-service platform](https://dashboard.coresignal.com/sign-in).
{% endhint %}
**Example response**
```json
{
"reason": "I searched for employees who are currently founders or co-founders and previously held engineering roles at Google (HQ: Mountain View, US), Meta (HQ: Menlo Park, US), Apple (HQ: Cupertino, US), Amazon (HQ: Seattle, US), or Microsoft (HQ: Redmond, US). I filtered for current founder/co-founder titles and past (not current) engineering positions at these five major tech companies, sorted by follower count to surface the most prominent profiles.",
"query": {
"sort": [
"followers_count"
],
"query": {
//Included search query
}
},
"data": [
{
"id": 123456789,
"full_name": "John Doe",
"professional_network_url": "https://www.professional-network.com/john-doe",
"active_experience_title": "Co-Founder",
"active_experience_company_id": 09876543,
"company_name": "Example Company",
"_score": 38.27471,
"followers_count": 2000,
"experience": [
{
"company_id": 19876543,
"company_name": "Example Tech",
"position_title": "Software Engineer",
"active_experience": 0
}
]
}
]
}
```
## Response structure
Each response contains a core set of fixed identifying fields for the requested entity, accompanied by additional fields that vary based on your query. Since the response's structure depends on what you searched for, integrations should dynamically parse the response rather than rely on a fixed field list beyond the essential ones below.
### Fixed fields
Locate the fixed fields listed for each entity below.
Company entity
| Data field | Description | Data type |
| -------------------------- | ------------------------------------------------ | --------- |
| `id` | Identification number | Integer |
| `company_name` | Company name | String |
| `professional_network_url` | The most recent profile Professional network URL | String |
| `_score` | Elasticsearch score | Float |
Employee entity
| Data field | Description | Data type |
| -------------------------- | ------------------------------------ | --------- |
| `id` | Identification number | Integer |
| `full_name` | Employee's full name | String |
| `professional_network_url` | Most recent profile URL | String |
| `company_name` | Company name | String |
| `active_experience_title` | Title of employee's current position | String |
| `_score` | Elasticsearch DSL score | Float |
Jobs entity
| Data field | Description | Data type |
| -------------- | ----------------------------------------- | --------- |
| `id` | Unified job identifier across all sources | Long |
| `title` | Standardized job title | String |
| `company_name` | Company name | String |
| `_score` | Elasticsearch score | Float |
### Dynamic fields
In addition to the fixed fields, the response includes root-level fields from your query's filter, along with the specific nested entries that matched, such as the relevant work experience, funding round, or job source, rather than the entire nested array. Because the dynamic part depends on the query, treat the response as a variable structure rather than assuming a fixed schema.
## Sorting
Both `/fast` and `/reasoning` support result sorting. Instead of a separate parameter, you indicate the preferred sort order within your natural language prompt, and the engine interprets it to apply the correct sorting in the generated query.
{% hint style="success" %}
#### Example
*"Find heads of engineering or CTOs at European fintech companies who have US work experience, sorted by profile\_score"*
{% endhint %}
The supported sort fields vary by entity. Default sorting also differs between endpoints – `/fast` defaults to `_score` for all entities, while `/reasoning` defaults to a field that surfaces the most prominent results.
| Entity | Supported sorting fields | /fast default sorting | /reasoning default sorting |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------------------------- |
| `company` | \_score
employees\_count
last\_funding\_amount
followers\_count
active\_job\_postings\_count
num\_news\_articles
last\_updated
| `_score` | `employees_count` |
| `employee` | \_score
followers\_count
profile\_score
| `_score` | `followers_count` |
| `job` | \_score
last\_updated
company\_employees\_count
| `_score` | `company_employees_count` |
## Pricing
API credits are deducted for each successful request that returns data or an Elasticsearch query. The cost varies based on the endpoint. Find the credit costs on the [Pricing](/pricing/pricing.md#agentic-search-api) page.
## 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 |
## Prompt examples
Here are a few examples of prompts that can be used for your projects.
{% prompt description="Find founders or co-founders who have previously held an engineering role at Google, Meta, Apple, Amazon, or Microsoft." %}
```markdown
Find founders or co-founders who have previously held an engineering role at Google, Meta, Apple, Amazon, or Microsoft.
```
{% endprompt %}
{% prompt description="Find VPs of Sales or Chief Revenue Officers who previously worked at Salesforce or HubSpot." %}
```markdown
Find VPs of Sales or Chief Revenue Officers who previously worked at Salesforce or HubSpot.
```
{% endprompt %}
{% prompt description="Find heads of engineering or CTOs at European fintech companies who have US work experience." %}
```markdown
Find heads of engineering or CTOs at European fintech companies who have US work experience.
```
{% endprompt %}
## Frequently asked questions
What are the core architectural and performance differences between /reasoning and /fast endpoints?
Both endpoint translate natural language into Elasticsearch DSL queries against the same data.
`/fast` uses a simplified schema and a specified entity type, optimized for speed and cost. Rate limits vary by [plan](/pricing/pricing.md#compare-monthly-plans), making it suitable for high-volume, programmatic workloads.
`/reasoning` employs the full data schema, automatically infers entity types, handles cross-search scenarios, and supports an optional clarification flow for ambiguous prompts. Rate limit is 10 req/hour, so it is used for complex, multi-criteria queries where precision matters more than latency.
Is semantic search available on Agentic Search API?
Semantic search is available on both endpoints and applies specifically to job titles. We enrich and expand queries with title synonyms to improve recall. Beyond title expansion, `/reasoning` provides deeper interpretation of the full prompt, leveraging the full schema and a more powerful model.
How do you ensure natural language to Elasticsearch translation quality, and do you conduct ongoing evaluations?
Translation is grounded in our actual index schemas, which constrain output to valid fields and correct query structures. On `/reasoning`, the clarification flow resolves ambiguity before query generation, and the `reason` field makes interpretation transparent. On both endpoints, you can run in query mode (`"return_data": false`) to inspect the generated Elasticsearch DSL before executing it.
For evaluations, we maintain an extensive suite of internal evaluation tests that grows with every improvement to the engine. These run continuously as we develop, serving as regression guardrails to ensure translation quality and search performance don't drift or degrade between releases.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.coresignal.com/agentic-search-api/agentic-search-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.