# 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:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Elasticsearch DSL query</strong></td><td>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.</td></tr><tr><td><strong>Data preview</strong></td><td>Receive matching data records directly in a single response – results are ready to use immediately.</td></tr></tbody></table>

## Endpoints

We offer several different API endpoints, each designed for specific use cases and data needs.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><a href="#v2-agentic_search-fast-endpoint"><code>/v2/agentic_search/fast</code> endpoint</a></td><td>This endpoint is optimized for speed and cost, ensuring rapid responses while minimizing resource consumption.</td></tr><tr><td><a href="#v2-agentic_search-reasoning-endpoint"><code>/v2/agentic_search/reasoning</code> endpoint</a></td><td>This endpoint is optimized to deliver highly accurate results, even for complex queries.</td></tr></tbody></table>

## `/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. With rate limits of up to **18 requests per second**, 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.

<table><thead><tr><th width="173.88671875">Parameter</th><th width="96.66796875">Type</th><th width="112.33984375">Required</th><th width="127.546875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>prompt</code></td><td>String</td><td>Required</td><td>–</td><td>Natural language query describing the employees you want to find.</td></tr><tr><td><code>return_data</code></td><td>Boolean</td><td>Optional</td><td><code>false</code></td><td>When <code>false</code>, returns an Elasticsearch DSL query. When <code>true</code>, returns preview data.</td></tr><tr><td><code>limit</code></td><td>Integer</td><td>Optional</td><td><code>20</code></td><td>Max results to return when <code>return_data</code> is <code>true</code>. Range: 1–100.</td></tr><tr><td><code>entity</code></td><td>String</td><td>Optional</td><td><code>"employee"</code></td><td>Target entity type. Currently only <code>"employee"</code> is supported.</td></tr></tbody></table>

### Output modes

The `return_data` parameter controls what is returned. Choose between a generated query for your own pipeline or receiving data directly.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><a href="#query-output-return_data-false"><strong>Query mode</strong></a></td><td><code>return_data: false</code> (default)<br><br>Returns the generated Elasticsearch DSL query. Use it to integrate it into your own requests or to inspect the generated query logic.</td></tr><tr><td><a href="#data-output-return_data-true"><strong>Data mode</strong></a></td><td><code>return_data: true</code><br><br>Executes the query and returns preview results directly. Up to 100 results are delivered in a single response.</td></tr></tbody></table>

#### 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`. Results are sorted by `_score` field in descending order.

#### 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 %}

## `/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.

<table><thead><tr><th width="173.88671875">Parameter</th><th width="96.66796875">Type</th><th width="112.33984375">Required</th><th width="127.546875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>prompt</code></td><td>String</td><td>Required</td><td>–</td><td>Natural language query, or clarification text, when continuing a session.</td></tr><tr><td><code>return_data</code></td><td>Boolean</td><td>Optional</td><td><code>false</code></td><td>When <code>false</code>, returns an Elasticsearch DSL query. When <code>true</code>, returns preview data.</td></tr><tr><td><code>allow_clarification</code></td><td>Boolean</td><td>Optional</td><td><code>false</code></td><td>When <code>true</code>, the engine may ask follow-up questions before executing a complex query.</td></tr><tr><td><code>session_id</code></td><td>String; null</td><td>Optional</td><td><code>null</code></td><td>Required when continuing a clarification session. Must match the <code>session_id</code> returned in the previous clarification response. If missing, treated as a new session.</td></tr><tr><td><code>entity</code></td><td>String</td><td>Optional</td><td><code>null</code></td><td>Target entity type. If <code>null</code> or omitted, the entity is inferred from the prompt. Accepted values: <code>employee</code>, <code>company</code>, <code>job</code>, <code>null</code>.</td></tr><tr><td><code>limit</code></td><td>Integer</td><td>Optional</td><td><code>20</code></td><td>Max results to return when <code>return_data</code> is <code>true</code>. Range: 1–100.</td></tr></tbody></table>

### Clarification flow

When `allow_clarification: true` and the engine identifies that the prompt is ambiguous, it returns a clarification request instead of executing the search. Clarifications 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 question 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
{
  "session_id": "abc123",
  "entity": "employee",
  "clarification_needed": true,
  "reason": "Please clarify whether you are looking for current or former employees.",
  "query": null,
  "data": null
}
```

{% 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": "abc123",
  "return_data": false,
  "allow_clarification": true,
  "limit": 20
}
```

{% endstep %}
{% endstepper %}

{% hint style="warning" %}
If `session_id` is missing from the follow-up request, the engine treats it as a new session and the original prompt context is lost.
{% endhint %}

### Output modes

The `return_data` parameter controls the output. You can either receive a generated query for your pipeline or retrieve the data directly. The output modes match those of the `/fast` endpoint.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><a href="#query-output-return_data-false-1"><strong>Query mode</strong></a></td><td><code>return_data: false</code> (default)<br><br>Returns the Elasticsearch DSL query that was generated. You can use it to incorporate into your own requests or to review the query logic.</td></tr><tr><td><a href="#data-output-return_data-true-1"><strong>Data mode</strong></a></td><td><code>return_data: true</code><br><br>Performs the query and provides preview results immediately. Up to 100 results are included in one response.</td></tr></tbody></table>

#### 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**

```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.",
  "return_data": false,
  "allow_clarification": false,
  "entity": null
}
```

{% 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`

When the `return_data: true` parameter is used, the endpoint internally builds and executes the Elasticsearch DSL query, then returns the results directly. In this mode, the Elasticsearch DSL query is not exposed.

The `limit` parameter in this mode controls the maximum number of results returned. The default value is `20` and the maximum value is `100`. Results are sorted by `_score` field in descending order.

**Example request**

```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.",
  "return_data": true,
  "allow_clarification": false,
  "limit": 1,
  "entity": null
}
```

{% 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 with each successful request, when the data or Elasticsearch query is returned. The cost depends on the endpoint used, the output mode, and, if data is returned, the number of results.

| Output mode          | Response                                                                                                                              | /fast search credits cost     | /reasoning search credits cost    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | --------------------------------- |
| `return_data: false` | Elasticsearch DSL query                                                                                                               | 2                             | 10                                |
| `return_data: true`  | <p>1–20 results returned<br>21–40 results returned<br>41–60 results returned<br>61–80 results returned<br>81–100 results returned</p> | <p>2<br>4<br>6<br>8<br>10</p> | <p>10<br>12<br>14<br>16<br>18</p> |

{% 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                                         |

## 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.


---

# Agent Instructions: 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:

```
GET https://docs.coresignal.com/agentic-search-api/agentic-search-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.