---
title: Venom Search
description: Turn on Venom Search, your org's own metasearch over official APIs and open data, and call it from the API, MCP or the CLI's web_search.
section: cloud
order: 216
audience: [user, builder, operator, agent]
sources: [services/nodejs-cloud/lib/search, services/nodejs-cloud/app/v1/search/route.ts, services/nodejs-cloud/app/api/admin/v1/settings/search/route.ts, services/nodejs-cloud/app/(console)/(shell)/settings/search, services/nodejs-cloud/migrations/0235_venom_search.sql, docs/adr/0079-venom-search.md]
features: [cloud.v1-search]
---

Venom Search asks several search engines at once, merges what they find and ranks it. It follows the design of
SearXNG, the open-source metasearch engine, but it is Venom's own code: see [ADR 0079](#why-our-own-code).

It is **off until you turn it on**. Until an owner or admin turns it on in **Settings → Search**, no search leaves
Venom and `POST /v1/search` answers `404 search_disabled`. It is a 404 because the route answered 404 before it
existed, so a venom CLI whose provider is Venom Cloud moves on to its own search backends.

## Engines

Every engine uses an official API or open data. None of them reads a search results page meant for people.

| Engine | Categories | What it returns | Needs |
|---|---|---|---|
| Brave Search | general, news, images | Web, news and image results from Brave's own index | a Brave Search API key: yours, or Venom's (below) |
| Wikipedia | general, people | Article titles and the passage that matched | nothing |
| Wikidata | general, people | Entities: label, short description, Q-id | nothing |
| OpenAlex | science, people | Papers (title, year, venue, authors, abstract); for people, researchers and their institution | nothing |
| ORCID | people, science | Researchers by name: ORCID iD and institutions | nothing |
| GitHub | code, people | Repositories (description, stars, language); for people, accounts | nothing |
| Hacker News | news, code | Stories with points and comments (Algolia's HN API) | nothing |
| Stack Overflow | code | Questions with score, answered state and tags (Stack Exchange API) | nothing |
| arXiv | science | Preprints: title, authors, abstract, date | nothing |
| Gravatar | people | For an email address only: the public profile (name, job, company, verified accounts). Only the address's SHA-256 hash is sent | nothing |
| Your SearxNG | general, news, images, science, code | Results from a SearxNG instance you run, with the engines it used | its URL |

A request picks **categories** (`general`, `people`, `code`, `science`, `news`, `images`; default `general`) and
every enabled engine of those categories is asked. It can name **engines** instead.

## Turn it on

In **Settings → Search** (`/settings/search`; owners and admins; everyone with `providers:read` can look):

1. Switch on **Use Venom Search**.
2. Turn engines on or off. Each row shows its health: average response time, the share of the last 20 calls that
   failed, and whether it is suspended.
3. Optional: paste your **Brave Search API key**. It is sealed in the vault and never shown again; only its last
   four characters are. Without one, Venom's own Brave key (`BRAVE_SEARCH_API_KEY` on the deployment) answers if
   this deployment has one and your org's **Use Venom's keys** switch (Providers) is on. Your key always comes first.
4. Optional: the URL of **your SearxNG**. Its JSON API must be allowed (`format: json` in its settings). Private and
   loopback addresses are refused.
5. Optional: **Keep search queries**. Off by default.

Agents with a member's key can do the same with `admin_search_get` and `admin_search_set`, and scripts with the admin
API: `GET /api/admin/v1/settings/search` reads the settings, the engines with their health and the recent queries;
`PUT /api/admin/v1/settings/search` takes `{enabled, engines, brave_key, searxng_url, log_queries}`, any of them.

## Search from the API

```bash
curl -s "$VENOM_CLOUD_URL/v1/search" \
  -H "Authorization: Bearer $VENOM_CLOUD_KEY" -H "content-type: application/json" \
  -d '{"query": "tokio runtime", "categories": ["code"], "limit": 5}'
```

| Field | | |
|---|---|---|
| `query` | required | up to 500 characters |
| `categories` | optional | list of categories, default `["general"]` |
| `engines` | optional | ask only these engines |
| `limit` | optional | 1 to 50, default 10 |
| `freshness` | optional | `day`, `week`, `month` or `year`, for engines that can filter by date |
| `country` | optional | two-letter code, for engines that take one (Brave) |

The body of the venom orchestrator's `POST /v1/search` works too, which is what the CLI's `web_search` sends to its
provider: `count` for `limit`, `time_range` for `freshness`, `allowed_domains` (keep only results from these domains
and their subdomains) and `blocked_domains` (drop them), at most 20 each. `language`, `answer` and `model` are accepted
and ignored: Venom Search gives results, not a written answer.

```json
{
  "object": "search.result",
  "backend": "venom-search",
  "id": "req_…",
  "query": "tokio runtime",
  "results": [
    { "url": "https://github.com/tokio-rs/tokio", "title": "tokio-rs/tokio", "snippet": "A runtime for writing reliable asynchronous applications with Rust.",
      "category": "code", "engines": ["github", "hackernews"], "score": 1.35, "published_at": "2026-11-01T10:00:00.000Z", "thumbnail": null, "extra": { "stars": 29000 } }
  ],
  "engines": [
    { "name": "github", "status": "ok", "results": 5, "ms": 312, "error": null },
    { "name": "stackexchange", "status": "timeout", "results": 0, "ms": 4000, "error": "timeout" }
  ],
  "cached": false,
  "cost_usd": 0
}
```

Each result lists every engine that found it. An engine that is slow, fails, is suspended or has nothing to ask
(Gravatar without an email address) is listed in `engines` with its status; it never fails the search.

Errors: `400 invalid_request` names the field (`param`), `404 search_disabled` when search is off, `429` for the
key's rate limit or the org's spend cap.

## From MCP and REST

On the [workspace MCP server](/docs/cloud/workspace-mcp.md) the tool is `workspace_web_search` (also callable as
`search_web`), with the same arguments and `format: "json"` for the full answer. Its REST twin is
`POST /api/v1/web/search`. An OAuth app's searches are booked to the org without a key.

## Studio research runs {#studio-research}

A Studio [research run](/docs/studio/research.md) searches through Venom Search and, under the same switch, also reads the
pages its results point to (public `https` addresses only, SSRF-guarded, 8 seconds and 1.5 MB each, no cookie or referrer)
and the World Bank's open data API (`api.worldbank.org`, no key). With search off, a run reaches nothing outside Venom: it
uses the model's own knowledge and marks every figure unverified. Its searches are booked with `source` `studio-research`.

## Provider search {#provider-search}

**Provider search for research runs** (off by default) lets Studio research runs also search through the web search the model
providers run themselves: OpenAI, Anthropic, Model Studio and Z.ai, with the org's own key (or Venom's, as "Use Venom's keys"
allows). It is separate from Venom Search: either one makes a run researched. It sends the research queries to that provider,
so an owner or admin turns it on here (`provider_search` on the admin API and `admin_search_set`); the page lists the providers
that could serve it and whose key each uses. Calls are booked under the model `provider-search`. Details: [Research
runs](/docs/studio/research.md#provider-search).

## From the CLI {#from-the-cli}

The venom CLI's `web_search` tool uses Venom Search once you are signed in to Venom Cloud (`venom cloud login`, or
`VENOM_CLOUD_URL` and `VENOM_CLOUD_KEY`) and your org has turned search on. It sends `POST /v1/search` with your cloud
key, after your own SearxNG (`VENOM_SEARCH_URL`) when you have one and before Brave, Tavily and DuckDuckGo. When the
CLI's provider is the cloud itself, its first search already reaches Venom Search, so the cloud is not asked twice.

While search is off the cloud answers 404 and the CLI stops asking it for the rest of the session. Any other error
(a spend cap, a rate limit) hands the search to the next backend. A gear that allows only self-hosted search never
uses it. See [The agent's tools](/docs/cli/tools.md#web).

## How results are ranked

An engine's results are ranked 1, 2, 3, … and each one earns the engine's weight divided by its rank. A page that
several engines found adds up their scores, so it ranks above a page only one engine found at the same place.
Addresses are normalised before they are compared: no scheme, no `www.`, no default port, no trailing slash, no
fragment, tracking parameters (`utm_*`, `fbclid`, `gclid`, …) removed and the rest sorted.

## Health and suspension

After three errors in a row an engine is suspended for a minute, then two, four and so on up to an hour. A rate
limit (429) or a refused key (401, 403) suspends it at once. After the suspension the next search tries it again,
and one success clears it.

## Cache

The same search by the same org within five minutes is answered from memory (`"cached": true`), without asking
the engines again and at no cost.

## Privacy and cost

- Engines get the query and nothing about who asked: no IP address, no key, no org name. The User-Agent names
  Venom Search only.
- `request_log` keeps metadata only (when, which key, which engines answered, the cost). The query text is kept
  only while **Keep search queries** is on, for 30 days, and turning it off deletes it.
- Every search is in Requests and Usage under the model `venom-search`. Open engines cost nothing. A Brave call is
  booked at $0.005, with your key or Venom's.

## Why our own code

SearXNG is licensed under the AGPL-3.0. Venom Search contains none of its code or engine files: it was written
from SearXNG's public descriptions of its design (engines as adapters, a fan-out with timeouts, merged and scored
results, categories, engine suspension, a short cache) and the engines' own API documentation. ADR 0079 in the
repository records the decision and the sources.
