Research (GenAI)

What Research does

The Research endpoint runs a custom, AI-powered analysis over a list of entities. Instead of returning a fixed enrichment schema, you describe the task — either as a natural-language query or as a prompt_template — and define the exact shape of the result with an output_schema. For each entity, the engine resolves its profile, optionally performs real-time web research, and returns structured JSON that conforms to your schema. This is ideal when an off-the-shelf enrichment doesn’t exist for your use case, for example:

Custom classification — e.g. B2B vs B2C, ICP fit, seniority or buying-role inference.
Fit scoring with reasoning — score each account or contact against a value proposition and explain why.
Campaign-ready copy — one-line segments or personalized openers tailored per entity. Each entity is processed independently against your prompt and schema, so a single request can research many records at once.

Endpoints

Research runs on two entity types. The concepts on this page apply to both; each endpoint page documents its own record fields, request shape, and examples.

Entity	Sync	Async
Businesses	`/v2/businesses/research/enrich`	`/v2/businesses/research/job`
Prospects	`/v2/prospects/research/enrich`	`/v2/prospects/research/job`

All are POST. Sync endpoints accept a single ID or a list of IDs; async endpoints take a list_id from an uploaded dataset — see v2 conventions and async jobs. Authenticate with your API key in the api_key header. See Getting your API key.

How it works

How It Works

Input: A list of entities (each identified by a business_id or prospect_id, with optional custom_fields) plus a parameters object containing either a query or a prompt_template, and an output_schema (required with prompt_template, optional with query).
Processing: For each entity, Explorium resolves the profile and builds a record context. When you pass a query, an internal LLM first generates an optimized prompt from your instruction, the available record fields, and the available research functions — and, if you didn’t supply an output_schema, generates one as well. When you pass a prompt_template, your prompt is used as-is. The engine then runs the prompt — performing web research where instructed — and produces structured output constrained to the schema.
Output: One result row per input entity, returned under data. Each successful row contains the generated fields defined by the output_schema; failed rows are returned with an _error field rather than being dropped.

`query` vs `prompt_template`

You must provide exactly one of query or prompt_template. Sending both, or neither, returns a validation error.

	`query`	`prompt_template`
What you write	A natural-language instruction describing the insight you want	A prompt with placeholders that reference fields on the `record`
Prompt construction	An internal LLM composes an optimized prompt from your instruction, the available `record` fields, and the available research functions	Your prompt is passed to the engine as-is, with no modification
Best for	End-user-facing flows (VP chat, Hub) and quick, general instructions	Precise, repeatable prompts; power users; programmatic/MCP access where the caller builds the prompt itself
Research functions	Selected automatically by the prompt generator	Invoked inline by the prompt author — up to two per template (see Research functions)
Custom fields	Available to the model as part of the entity context	Referenced explicitly, e.g. `{{ record['campaign_name'] }}`
`output_schema`	Optional — generated automatically from your instruction if omitted	Required — omitting it returns a validation error

The `record` context

When rendering a prompt_template (and when the model composes a prompt from a query), each entity is represented by a record object. The record contains:

Explorium profile fields resolved from the identifier. For businesses, fields such as record['organization_name'] and record['description']. For prospects, fields such as record['full_name'], record['job_title'], and record['organization_name'].
Any custom_fields you supplied for that entity — for example record['campaign_name'].

Reference these in a prompt_template using {{ record['field_name'] }}. Custom fields are merged into the same record namespace as the profile fields, so they’re referenced the same way. The full field list lives on each endpoint page: businesses and prospects.

Real-time web research

What sets Research apart from standard enrichments is that the engine can ground its analysis in live web data, not just the data already on file. Per entity, it can:

Run a SERP search and use the top results as context for the model.
Search and scrape the most relevant web pages and pass that content to the model as grounding context. You steer this directly from your instruction — for example, “…use web search to validate if the description is insufficient” or “…use web search to supplement missing context.” When the resolved profile is enough, the model can answer from it; when it isn’t, the model can reach out to the web.

Because some rows trigger live web lookups, per-entity latency varies and can take several seconds. Size your batches and set client timeouts accordingly.

v2: this endpoint accepts either a single ID (a string) or a list of IDs — the separate /bulk_enrich route is gone. See v2 conventions.

Research functions

Inside a prompt_template, you can call research functions to ground the analysis in live web data. Render them with {{ ... }} just like a record field: the function runs first, and its output — SERP results or scraped page text — is injected into the prompt as context before the model reasons over it. Their arguments are typically built from record fields (e.g. record['organization_name'], record['url']). You can use up to two research functions in a single prompt_template.

These functions apply to prompt_template only. When you pass a query, the prompt generator selects and invokes the appropriate research functions automatically based on your instruction — you don’t call them explicitly.

`ReadMostRelevantLinks`

Runs a SERP search for query and scrapes the top max_results result pages, injecting their combined content into the prompt as grounding context. Use it when the company or person isn’t well described by the resolved profile alone and you want fresh, broad web context.

string

required

The search query to run. Commonly built from a record field, e.g. record['organization_name'].

integer

The number of top SERP results to fetch and scrape.

{{ ReadMostRelevantLinks(query=record['organization_name'], max_results=4) }}

{
  "business_id": "8adce3ca1cef0c986b22310e369a0793",
  "parameters": {
    "prompt_template": "{{ ReadMostRelevantLinks(query=record['organization_name'], max_results=4) }}\n\nUsing the company description {{ record['description'] }} and website {{ record['url'] }}, classify whether {{ record['organization_name'] }} primarily sells to businesses (B2B) or consumers (B2C). Explain your reasoning.",
    "output_schema": {
      "type": "object",
      "properties": {
        "btb_btc": {
          "type": "string",
          "enum": ["B2B", "B2C", "Both"],
          "description": "Whether the company is primarily B2B, B2C, or both"
        },
        "reasoning": {
          "type": "string",
          "description": "Brief explanation for the classification"
        }
      },
      "required": ["btb_btc", "reasoning"]
    }
  }
}

`ReadUrlText`

Scrapes the text content of a single URL and injects it into the prompt as grounding context. Use it when you already know the exact page to read — most often the entity’s own website via record['url'].

string

required

The URL of the page to scrape, e.g. record['url'].

{{ ReadUrlText(url=record['url']) }}

{
  "prospect_id": "5d86c0d8eae6bdd60515685670a4a2ad49981945",
  "parameters": {
    "prompt_template": "{{ ReadUrlText(url=record['url']) }}\n\nEvaluate whether {{ record['full_name'] }} ({{ record['job_title'] }} at {{ record['organization_name'] }}) is a strong fit for an enterprise data platform. Use summary {{ record['summary'] }}, skills {{ record['skills'] }}, and company website content from {{ record['url'] }}.",
    "output_schema": {
      "type": "object",
      "properties": {
        "fit_score": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "description": "Prospect fit score from 1 to 10"
        },
        "reasoning": {
          "type": "string",
          "description": "Brief explanation for the score"
        }
      },
      "required": ["fit_score", "reasoning"]
    }
  }
}

Using two functions together

You can combine both functions in one prompt_template (the two-function maximum). Here the model reads the company’s own site with ReadUrlText and supplements it with broader web results from ReadMostRelevantLinks before answering.

{
  "business_id": "8adce3ca1cef0c986b22310e369a0793",
  "parameters": {
    "prompt_template": "{{ ReadUrlText(url=record['url']) }}\n\n{{ ReadMostRelevantLinks(query=record['organization_name'], max_results=3) }}\n\nUsing the company's own website and the most relevant web results, summarize what {{ record['organization_name'] }} does and identify its primary target market.",
    "output_schema": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string",
          "description": "One-paragraph summary of what the company does"
        },
        "target_market": {
          "type": "string",
          "description": "The company's primary target market"
        }
      },
      "required": ["summary", "target_market"]
    }
  }
}

A prompt_template may reference at most two research functions. Adding a third returns a validation error. Each function that runs performs live web I/O, so it adds latency to that row — prefer ReadUrlText when you know the exact page, and reserve ReadMostRelevantLinks for cases that need broader discovery.

Per-call credit usage

The Research endpoints support the opt-in Per-Call Credit Usage header. Send credit-usage: true to receive a credit_usage object alongside the response, reporting the exact credits deducted for the call. This is the recommended way to track research costs while you tune prompts and schemas.

credit-usage: true

Best practices

Be explicit in your schema. Use clear field descriptions, and enum / minimum / maximum constraints, so the model returns consistent, parseable values.
Keep outputs focused. Smaller, well-scoped schemas produce more reliable results than large free-form objects.
Tell the model when to use the web. If a task may need information beyond the resolved profile, say so in your instruction (e.g. “use web search to supplement missing context”).
Prefer prompt_template for repeatable pipelines where you need full control over wording, injected fields, and inline research functions; use query for quick, natural-language instructions.
Resolve identifiers first with Match Businesses or Match Prospects so the engine has a profile to work from.
Attach context with custom_fields (e.g. campaign name, segment) rather than hard-coding it into every prompt.
Handle _error rows. Iterate over data and check for _error before reading the generated fields.

Rate limits are counted per query, not per request. Each entity in the businesses / prospects array counts as a separate query toward your rate limit. A single request that researches 50 entities consumes 50 queries from your 200-queries-per-minute limit — not 1. Batching reduces HTTP/network overhead, but it does not reduce the number of queries counted against your rate limit. Size your batches accordingly.

Errors

object

Returned when the request body is invalid — for example when both query and prompt_template are provided, when neither is provided, when prompt_template is used without an output_schema, or when the output_schema is malformed.

Show properties

object[]

A list of validation errors, each with loc (location of the error), msg (human-readable message), and type.

See Error Handling for the full list of status codes and retry guidance.

Endpoint reference

Businesses research

Business record fields, request shape, and examples

Prospects research

Prospect record fields, request shape, and examples

Getting started

Businesses

Business enrichments

Prospects

Prospect enrichments

Async jobs

Autocomplete

Credits

Events & Webhooks

Research (GenAI)

What Research does

Endpoints

How it works

Real-time web research

Research functions

`ReadMostRelevantLinks`

`ReadUrlText`

Using two functions together

Per-call credit usage

Best practices

Errors

Endpoint reference

Businesses research

Prospects research

​What Research does

​Endpoints

​How it works

​Real-time web research

​Research functions

​ReadMostRelevantLinks

​ReadUrlText

​Using two functions together

​Per-call credit usage

​Best practices

​Errors

​Endpoint reference

Businesses research

Prospects research

What Research does

Endpoints

How it works

Real-time web research

Research functions

`ReadMostRelevantLinks`

`ReadUrlText`

Using two functions together

Per-call credit usage

Best practices

Errors

Endpoint reference