Agentic Search API

The Coresignal Agentic Search API is a natural language search API for querying professional data. Instead of writing structured queries, you describe what you need in natural language, and the API handles the rest.

Built for agentic workflows, LLM pipelines, and AI-powered applications, it eliminates the need to manually construct Elasticsearch queries. Whether you are enriching leads, building a recruitment tool, or powering an AI agent with business data, Agentic Search API gives you a faster path from prompt to data.

Depending on your use case, there are several response methods available:

Elasticsearch DSL query

Receive a generated Elasticsearch query to run yourself via multi-source API. Useful when you need control over execution or want to inspect query logic.

Data preview

Receive matching data records directly in a single response – results are ready to use immediately.

Endpoints

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. Request access for testing

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

Parameter	Type	Required	Default	Description
prompt	String	Required	–	Natural language query describing the employees you want to find.
return_data	Boolean	Optional	false	When false, returns an Elasticsearch DSL query. When true, returns preview data.
limit	Integer	Optional	20	Max results to return when return_data is true. Range: 1–100.
entity	String	Optional	"employee"	Target entity type. Currently only "employee" is supported.

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.

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

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

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

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:

Request access

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.
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.
session_id	String; null	Optional	null	Required when continuing a clarification session. Must match the session_id returned in the previous clarification response. If missing, treated as a new session.
entity	String	Optional	null	Target entity type. If null or omitted, the entity is inferred from the prompt. Accepted values: employee, company, job, null.
limit	Integer	Optional	20	Max results to return when return_data is true. Range: 1–100.

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.

1

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.

{
  "session_id": "abc123",
  "entity": "employee",
  "clarification_needed": true,
  "reason": "Please clarify whether you are looking for current or former employees.",
  "query": null,
  "data": null
}

If allow_clarification: false, the reason field contains a short explanation of the generated query or results.

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

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.

reason . If clarification_needed is true, this field contains the clarification request. Otherwise, it contains a short explanation of the generated query or results.

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

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

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

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

Request access

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	1–20 results returned 21–40 results returned 41–60 results returned 61–80 results returned 81–100 results returned	2 4 6 8 10	10 12 14 16 18

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.

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

Request access