AI Research

AI Research takes a task written in plain language and runs a full research loop against it: it plans search queries, runs them, opens and reads the pages worth reading, decides whether it has enough, and writes a final report — with both a human-readable summary and a machine-readable payload. It is the one asynchronous product in the API: a run returns a session_id immediately, and the result is collected from Get Session Status.

When to use it

Reach for AI Research when the answer does not exist on a single page and has to be assembled:

company and counterparty intelligence
risk, sanctions and adverse-media checks
market, competitor and pricing overviews
due diligence write-ups that must cite their sources
analyst work you want repeated the same way every time

If you already know the page you want, AI Extract is cheaper and faster. If you only need a ranked list of links, use Search. If you need one field from one provider, use a Data Source.

How a run works

One run is a loop. Each iteration:

Plan — the planner proposes the next search queries, and may propose data source calls.
Search — the queries run and return ranked results.
Read — pages worth reading are fetched and their content extracted.
Reflect — the run decides continue, sufficient or finish, and records what is still missing.

When the loop stops, a finalizer model writes the report from everything gathered. The iteration log — queries, result counts, extracted pages, reflection notes, data source calls — is kept with the session, so a run can be audited after the fact.

Starting a run

curl -X POST "https://api.neuralverge.ai/functions/v1/run-research" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Profile Acme GmbH: ownership, management, recent litigation and any sanctions exposure. Cite sources.",
    "settings": {
      "model": "core",
      "finalizer_model": "gemini-3.0-pro",
      "country_code": "EU"
    }
  }'

The response is the session to poll:

{ "session_id": "11111111-1111-1111-1111-111111111111" }

Then poll until it settles:

curl "https://api.neuralverge.ai/functions/v1/get-session-status?session_id=11111111-1111-1111-1111-111111111111" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

status moves through queued and running to complete or failed; results appears once the run is complete. Poll every 2 to 5 seconds — see Errors & Rate Limits.

Depth: the `model` setting

settings.model picks how hard the run works. It sets the iteration budget and the price of the run.

Tier	Iterations	Searches per iteration	Pages read	Points
`lite`	1	1	up to 3	20
`base` (default)	1	2	up to 8	50
`core`	2	3	up to 20	100
`pro`	3	4	up to 50	200
`ultima`	4	5	up to 100	400

lite answers a narrow question from the first few hits. ultima keeps going for four rounds and reads up to a hundred pages — use it when coverage matters more than latency.

The finalizer

settings.finalizer_model chooses the model that writes the report. It changes the quality, tone and latency of the write-up, not what was gathered. Available: gemini-3.0-pro (default), gemini-3.0-flash, gemini-2.5-pro, gemini-2.5-flash, gpt-5.4, gpt-5.4-mini, gpt-5, gpt-5-mini, claude-sonnet-4.6, claude-opus-4.6.

Settings reference

Setting	Type	Description
`model`	string	Depth tier: `lite`, `base`, `core`, `pro`, `ultima`. Default `base`.
`finalizer_model`	string	Model that writes the report. Default `gemini-3.0-pro`.
`search_enabled`	boolean	Default `true`. Set `false` to run without web search — the run then works only from the data sources you allow, and the tier’s points are not charged.
`country_code`	string	`US` or `EU`. Where searches and page loads come from.
`device_type`	string	`desktop` or `mobile`.
`max_iterations`	number	Lower the tier’s iteration count. Cannot raise it.
`searches_per_iter`	number	Lower the tier’s searches per iteration.
`max_pages`	number	Lower the tier’s page budget.
`max_searches`	number	Cap total searches across the run.
`report_detail_mode`	string	`short`, `medium`, `detailed`, or `user_exact` to follow the shape your instructions ask for.
`extract_schema_json`	string	JSON Schema, as a string. The machine payload then follows your schema instead of the default report shape.
`data_source_ids`	string[]	Data sources the run may call as tools — see below.

Every budget setting can only narrow what the tier already allows, so a run can never cost more than its tier.

Using data sources as tools

List data source ids in settings.data_source_ids and the run can call them mid-loop instead of guessing from web pages: a company number from a registry, a LinkedIn profile, reviews for a product. The planner decides when a call is worth making, and every call is recorded in the iteration log.

{
  "instructions": "Does ACME LTD (UK) have filings that contradict its website claims?",
  "settings": {
    "model": "pro",
    "data_source_ids": ["<uk-companies-id>", "<uk-company-filings-id>"]
  }
}

Data source calls are billed at the data source’s own price, on top of the tier.

What a finished run returns

Field	Description
`session_id`	The run this result belongs to.
`human`	Markdown report, ready to show an analyst or paste into a ticket.
`machine`	Structured payload — your schema when `extract_schema_json` is set, the default report shape otherwise.
`cost`	`total_points`, split into `search_points` and `data_source_points`.
`limits` / `executed`	The budgets the run was given and what it actually used: searches and iterations.

Pricing

A run costs the tier’s points, plus the points of any data source it called. Nothing is charged for the tier when search_enabled is false. A run that fails before any work is dispatched is not charged.

Next steps

Run Research — the full request and response reference
AI Extract — structured fields from a page you already know
Search — ranked results with no synthesis step
Data Sources — the providers a run can call as tools
Errors & Rate Limits — polling, retries and limits

AI Research is not available over the MCP server: MCP tools return their result inside the tool call, and a research run is asynchronous. Start runs over the REST API instead.

Introduction

Product

API Basics

Integrations

AI Research

AI Research

When to use it

How a run works

Starting a run

Depth: the `model` setting

The finalizer

Settings reference

Using data sources as tools

What a finished run returns

Pricing

Next steps

​AI Research

​When to use it

​How a run works

​Starting a run

​Depth: the model setting

​The finalizer

​Settings reference

​Using data sources as tools

​What a finished run returns

​Pricing

​Next steps

AI Research

When to use it

How a run works

Starting a run

Depth: the `model` setting

The finalizer

Settings reference

Using data sources as tools

What a finished run returns

Pricing

Next steps