# 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.<br><br><a href="https://dashboard.coresignal.com/sign-up">Start the free trial</a></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.<br><br><a href="https://coresignal.com/contact-us/?utm_source=web&#x26;utm_medium=public-docs&#x26;utm_campaign=agentic-access">Request access for testing</a></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 **1 request 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 data 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. Accepted values: <code>employee</code>, <code>company</code>, <code>job</code>.</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**

{% 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": {
    "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.

<details>

<summary>Company entity</summary>

| 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    |
| `website`                  | Company's website                                                                             | String    |
| `unique_domain`            | Indicates if the domain is unique                                                             | Boolean   |
| `size_range`               | Company size based on employee count range (as selected by the company profile administrator) | String    |
| `employees_count`          | Number of employees on Professional network who associated their experience with the company  | Integer   |
| `industry`                 | Company's industry                                                                            | String    |
| `hq_country`               | Country the company is based in (as parsed by our in-house country parser)                    | String    |
| `company_logo`             | Base64-encoded image data of the company's logo                                               | String    |
| `_score`                   | Elasticsearch score                                                                           | Float     |

</details>

<details>

<summary>Employee entity</summary>

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

</details>

<details>

<summary>Jobs entity</summary>

| Data field     | Description                                     | Data type |
| -------------- | ----------------------------------------------- | --------- |
| `id`           | Unified job identifier across all sources       | Long      |
| `created_at`   | Timestamp when the job record was first created | Timestamp |
| `title`        | Standardized job title                          | String    |
| `location`     | Job location                                    | String    |
| `company_name` | Company name                                    | String    |
| `_score`       | Elasticsearch score                             | Float     |

</details>

**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,
  "limit": 1,
  "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
[
  {
    "id": 123456789,
    "full_name": "John Doe",
    "professional_network_url": "https://www.professional-network.com/john-doe",
    "headline": "Co-Founder | Example Company",
    "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, semantic search, 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.

{% hint style="warning" %}

#### Limited access

* The /reasoning endpoint uses a more powerful model for complex, multi-step prompts
* It's ideal for building smart AI assistants and conversational AI tools

Contact our team and get access for testing:

<a href="https://coresignal.com/contact-us/?utm_source=web&#x26;utm_medium=public-docs&#x26;utm_campaign=agentic-access" class="button primary">Request access</a>
{% endhint %}

### 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>session_id</code></td><td>String</td><td>Required</td><td>–</td><td>Required field for sending a request and continuing a clarification session. Must match the <code>session_id</code> returned in the previous clarification response. IDs are in UUID v4 format.</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>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>

### Prompt interpretation

Since the `/reasoning` endpoint uses semantic search 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=""reason" field example" overflow="wrap" %}

```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.",
  "data": [
    {
...
```

{% 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",
  "entity": "employee",
  "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,
  "limit": 20
}
```

{% endstep %}
{% endstepper %}

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

{% 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,
  "entity": null
}'
```

{% 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": {
    "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**

{% 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,
  "limit": 1,
  "entity": null
}'
```

{% 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
{
  "data": [
    {
      "id": 123456789,
      "full_name": "John Doe",
      "professional_network_url": "https://www.professional-network.com/john-doe",
      "headline": "Co-Founder | Example Company",
      "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 %}

{% hint style="warning" %}

#### Request access&#x20;

* The /reasoning endpoint uses a more powerful model for complex, multi-step prompts
* It's ideal for building smart AI assistants and conversational AI tools

Contact our team and get access for testing:

<a href="https://coresignal.com/contact-us/?utm_source=web&#x26;utm_medium=public-docs&#x26;utm_campaign=agentic-access" class="button primary">Request access</a>
{% endhint %}

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

{% hint style="warning" %}

#### Request access&#x20;

* The /reasoning endpoint uses a more powerful model for complex, multi-step prompts
* It's ideal for building smart AI assistants and conversational AI tools

Contact our team and get access for testing:

<a href="https://coresignal.com/contact-us/?utm_source=web&#x26;utm_medium=public-docs&#x26;utm_campaign=agentic-access" class="button primary">Request access</a>
{% endhint %}


---

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