WebSearch

WebSearch is the batch search API. It accepts one or more queries and returns deduplicated, structured search results for applications or agents to consume directly. Creation is always asynchronous; the Node SDK's wait() only waits for the run to finish. This page introduces the problems it solves and its core capabilities first, then the current call surface.

What it solves

• Agents need live web information: model training data has a cutoff, and fixed knowledge bases cannot cover changing facts. WebSearch turns "check what the web says right now" into one structured API call.
• Building your own search aggregation is expensive: multi-engine calls, cross-engine deduplication, reranking, and summarization all happen server-side; your application handles a structured WebSearchResults object.
• Submit a batch of questions at once: a single run takes 1–20 queries, fitting the "one topic, many angles" batch shape without queueing query by query.
• Retrieval scope must be controllable: site_whitelist / site_blacklist constrain or exclude sites, freshness filters by recency, and language and objective state language preference and retrieval intent.

Core capabilities

Capability	Description
Batch queries	One run submits 1–20 queries
Multiple engines	engines selects search engines; results come back unified
Dedup and rerank	Cross-query, cross-engine dedup (total_unique_results); rerank enables LLM reranking
Summaries	summarize generates a summary per result
Scope control	freshness, language, site_whitelist / site_blacklist, objective
Structured results	Each hit includes title, URL, snippet, and other fields, ready for programmatic use
Pure async pipeline	No human-interaction events; fits as the retrieval step of multi-step agent flows

Typical scenarios

• Batch-retrieve public information around keywords as content-planning input (see the SEO content planner agent).
• Retrieve public signals per candidate and assemble structured profiles (see the Sales lead agent and the Recruiting sourcing agent).

When to use it

• You need a structured list of search hits that your application processes and judges.
• Targets are public web pages; no sign-in or page actions are required.
• Seconds-to-minutes turnaround satisfies the flow.

To open pages and act on them, use DoAnything; for a cited, drafted report, use DeepResearch; for long-lived page monitoring, use Track.

Request fields

POST /api/v1/projects/{pid}/web_search/runs
Authorization: Bearer wa_...
Content-Type: application/json

Supported fields include queries (required), engines, max_results_per_query, rerank, summarize, freshness (month / year), language, objective, site_whitelist, and site_blacklist.

Node SDK

const search = await qoni.webSearch.run({
  token,
  prompt: ["browser automation 2026", "agentic browser"],
  maxResultsPerQuery: 5,
  siteWhitelist: ["github.com"],
});
const result = await search.wait();
console.log(result.output);

The high-level handle supports status(), events(), wait(), cancel(), and attach(). There is no runAsync(), refine(), sendFollowup(), or client.web_search.get() method.

Results and lifecycle

output / results is a WebSearchResults object with results, total_unique_results, is_summarized, and possibly engine_answer. dedup_count indicates how many queries or engines matched a result; it is not a truth guarantee.

GET /api/v1/projects/{pid}/web_search/runs/{run_id}
GET /api/v1/projects/{pid}/web_search/runs/{run_id}/events
POST /api/v1/projects/{pid}/web_search/runs/{run_id}/cancel

WebSearch does not expose messages, refine, or follow-up routes. Start a new run for a new query.