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

/v2/agentic_search/fast endpoint

This endpoint is optimized for speed and cost, ensuring rapid responses while minimizing resource consumption. Start the free trial

/v2/agentic_search/reasoning endpoint

This endpoint is optimized to deliver highly accurate results, even for complex queries. Start the free trial

Agentic Search API Playground

Explore the Agentic Search API in our self-service playground. For more details, see the Agentic Search API Playground topic.

/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, 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.
limit	Integer	Optional	20	Max results to return when return_data is true. Range: 1–100.
entity	String	Optional	"employee"	Target entity type. Accepted values: employee, company, job.
threshold	Float	Optional	1	Set the minimum confidence score for semantic search.

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 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 preview results directly. Up to 100 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

// 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"
}'

Get your API Key from Coresignal's self-service platform.

Example response

{
  "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"
  ]
}

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.

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

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

Jobs entity

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

Example request

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"
}'

Get your API Key from Coresignal's self-service platform.

Example response

[
  {
    "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
  }
]

How to test

1

Get your API key

Log in to the Coresignal dashboard and copy your API key. It is mandatory for your authentication, and you must pass it as the apikey header in every request.

2

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.

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,
  "limit": 5,
  "entity": "employee"
}'

3

Get data

If everything is set up correctly, you will receive a list of matching records within seconds.

/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.
limit	Integer	Optional	20	Max results to return when return_data is true. Range: 1–100.
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.

"reason" field example

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

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.

1

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.

{
  "reason": "Please clarify whether you are looking for current or former employees.",
  "session_id": "2bf83608-98f4-400b-8724-ec96c5b4141b",
  "allow_clarification": true
}

2

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.

{
  "prompt": "I am looking for current employees.",
  "session_id": "2bf83608-98f4-400b-8724-ec96c5b4141b",
  "return_data": true,
  "allow_clarification": true,
  "limit": 20
}

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.

Query mode

return_data: false (default) Returns the Elasticsearch DSL query that was generated. You can use it to incorporate into your own requests or to review the query logic.

Data mode

return_data: true Performs the query and provides preview results immediately. Up to 100 results are included in one response.

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

// 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
}'

Get your API Key from Coresignal's self-service platform.

Example response

{
  "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"
  ]
}

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

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

Get your API Key from Coresignal's self-service platform.

Example response

{
  "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
    }
  ]
}

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.

Example

"Find heads of engineering or CTOs at European fintech companies who have US work experience, sorted by followers_count"

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, output mode, and the number of results. Find the credit costs on the Pricing page.

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.

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.

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