---
title: Research runs
description: How Studio researches and writes a report on the server — plan with goals, parallel researchers over Venom Search, scholarly works and World Bank data, an analysis per section, the build and a review — with the intensity and agent controls, budgets, and what happens when research is off.
section: studio
order: 55
audience: [user, builder, agent]
sources: [services/nodejs-cloud/lib/studio/research/run.ts, services/nodejs-cloud/lib/studio/research/provider-search.ts, services/nodejs-cloud/migrations/0367_search_provider_search.sql, services/nodejs-cloud/lib/studio/research/premises.ts, services/nodejs-cloud/migrations/0366_studio_research_premises.sql, services/nodejs-cloud/lib/studio/research/pure.ts, services/nodejs-cloud/lib/studio/research/report.ts, services/nodejs-cloud/lib/studio/research/sources.ts, services/nodejs-cloud/lib/studio/mcp.ts, services/nodejs-cloud/app/api/cron/studio-research/route.ts, services/nodejs-cloud/migrations/0365_studio_research_runs.sql]
features: []
---

Ask a [quick chat](/docs/agents/quick-chat.md) with Venom Studio in its picker for a report, a briefing, an analysis or a deck about
a topic, and the cloud researches it before anything is built. The work is run by the server step by step, not left to the
model, so a small model gets the same process as a large one. The chat shows a **plan card** that updates as each step runs.

```text
Create a venom studio html artifact analyzing the aftermath of the plaza accord
deep research, 6 agents: a briefing on Japan's lost decade
```

## The steps {#steps}

1. **Premises.** The request's checkable facts (dates, names, places, who did what) are found and settled before anything
   else, each on its own ([below](#premises)). The plan cannot change them.
2. **Plan.** One model call writes the plan from the settled facts: the question restated, the audience, **3 to 6 goals** (what the reader must be able to answer or decide, and the evidence each
   needs), the research questions (each tied to a goal), the outline section by section (each tied to a goal, with the visual
   it needs: a chart, a table, a timeline or none) and the data series wanted. The goals head the plan card. Standard needs
   6 to 8 outline sections and Deep 8 to 10: a shorter plan is asked once more. A plan that moves a settled subject to another
   year (and builds its questions on it) is asked once more with the settled fact, and every plan text is then held to it in
   code: a year written next to the subject becomes the settled one.
3. **Research.** Each question is a researcher task. Up to *max agents* researchers work at once. A researcher asks the model
   for search queries (web, scholarly or news) and, where useful, World Bank data series; runs the searches; reads the best
   pages (distinct sites first); and asks the model to write **findings notes**: a claim, the figures behind it (value, unit,
   period, entity, source), the sources that support it and a confidence. A figure whose number is found in its source's text
   is *verified*; any other is marked *unverified* wherever it appears. A researcher that fails is shown failed on the card and
   the run goes on without it.
4. **Extra round.** A goal left with fewer than two sourced findings, or one the review (step 6) marks *not met*, gets one more
   targeted research round (standard: one in all; deep: up to two; quick: none), budget allowing. After a review's round,
   only that goal's sections are written again, the artifact gets a new version and the review runs once more.
5. **Analysis.** Each outline section is written from the notes for its goal: a takeaway that states the finding, two to four
   paragraphs of analysis (what happened, why, what the numbers show, the strongest competing view, what is uncertain) with
   every researched claim citing its source. Then the thesis, the executive summary, where sources disagree, the limitations,
   the assumptions and what to verify. Deep runs also cross-check the sections against each other and redraft the ones that
   contradict or miss their purpose. With research off, the budget the research did not use goes to a second analysis pass
   per section (the mechanism step by step, the counter-view's best case, what would show the claim wrong), as far as it
   allows after the overview and the review.
6. **Build.** The artifact is built in code from that data, never from markup a model wrote. Every factual sentence carries a
   numbered citation: one the analysis gave, or the sources of the note it restates; a sentence with a figure no note backs is
   labelled *(unverified)*. A run that found no source says so at the top. The card and the answer give the share of factual
   statements that cite a source. Charts and tables are drawn only
   from researched figures (a series with unverified values says so in its legend, and every chart names its sources). A page
   is the default; a request that says html gets an html page on the org theme, and one that says slides or deck gets a deck.
7. **Review.** One model pass checks the report against the goals and the notes and marks each goal *met*, *partly met* or
   *not met*. Code then holds it to the evidence: a goal none of whose notes cites a real source (a page, a paper, a data series,
   not model knowledge) is at most *partly met*, and on a run with no source at all the review may not call anything sourced. The sections it flags (and any that cite nothing although sources exist, or are missing) are redrafted once, and
   the artifact gets a reviewed version. It also checks the report's **frame**: when the report's own evidence contradicts its
   title, its restated question or a premise (every section says 1985, the title says 1975), the run repairs it once. The
   finding stands only when the notes or sections carry the value, and never over a premise a source settled. The title, the
   question and the sections are held to it, the artifact is renamed, and research questions built on the wrong year are
   dropped and asked again (budget allowing) before the review runs once more.
8. **Answer.** The chat's answer links the artifact and says what was done, how many distinct sources were used, each goal's
   status, the assumptions and what is worth verifying.

A report has: the answer in brief, key figures, the executive summary, the premises checked, one numbered section per outline
entry with its chart, table or timeline, the other view and what is uncertain, where sources disagree, every figure used, the
goals and their status, a methodology note, the limitations, and a numbered list of the sources the findings cite (a result a
researcher looked at and did not use is not listed). A chart's point marked `*` is a value not found in its source's text.
Links in an html artifact cannot be followed inside its sandbox, so each source also shows its full address as text.

## Premises {#premises}

A production run on the `normal` gear let its plan "correct" the 1987 Plaza Accord to 1975 and researched the wrong decade. So
no single model call may rewrite what the request states:

- One call lists the request's checkable premises: what it is about, what is claimed, and the value as the request says it
  (kept only when the request says it). If that call fails, years in the request are found by rule.
- **With research on**, each premise is looked up: one search, one page read (a result about the subject), and the fact read
  from that page. The page confirms the request's value only when that value stands near the subject's name in its text, and the
  card cites the page. A correction from a page also needs one of the two independent answers below to agree with it (a page
  can carry other dates: an essay's own date was once read as the accord's); otherwise the request's wording is kept, unconfirmed.
- **With research off** (or when the page does not say), the fact is asked twice, in different words, each with nothing else in
  context: neither question shows the request or the other answer. A correction stands only when both answers agree and differ
  from the request. When they disagree, the request's wording is kept and the premise is flagged **unconfirmed**.

The plan card lists each premise as *checked*, *corrected* (with what the request said) or *unconfirmed*, with its source or
"model knowledge, unverified". The answer says each once, under "Premises checked".

## Controls {#controls}

With Studio in the picker, the prompt box shows two more pills. Both are remembered for you and go with each message.

| Intensity | What it does | Roughly |
|---|---|---|
| Quick | No run: the agent makes the artifact in its own turn, following the `studio-artifact` skill. For small asks or content you supply. | 5 to 12 model calls |
| Standard (default) | 6 to 8 sections, 5 research questions, 3 queries and 3 pages each, one extra round, one review fix pass. | 20 to 35 model calls; caps: 45 calls, 30 searches, 24 pages, 8 data series, 30 minutes |
| Deep | 8 to 10 sections, 9 questions, 4 queries and 4 pages per round, two rounds each, up to two extra rounds, a cross-check. | 50 to 100 model calls; caps: 120 calls, 90 searches, 72 pages, 20 data series, 90 minutes |

**Agents** (1 to 8, default 3) is how many researchers and section writers work at once. More finish sooner; the caps stay the
same. Words in the message win over the pills: "deep research", "standard research", "no research" or "quick draft", and
"6 agents" or "four researchers". A request that only edits an artifact, supplies its own text ("a slide with this text"), or
asks for a mockup, a form or a title card keeps the quick path.

Model calls go through the chat's [gear](/docs/agents/quick-chat.md) and are booked to you like any chat. Every call asks for one
small JSON answer; an unreadable one is asked again once with the reason, then in a simpler shape, and every step has a way on
without the model, so a weak gear (eco, qwen) still finishes.

## Sources {#sources}

Research reaches only what [Settings → Search](/docs/cloud/search.md) allows: Venom Search, provider search, or both. With
neither on, nothing leaves Venom.

- **Venom Search** (while it is on): the org's engines, by category. Web and reference (Brave when a key is set, Wikipedia, Wikidata, the org's
  SearxNG), news, and scholarly works from OpenAlex and arXiv. Each search is booked like any other (`source` `studio-research`).
- **Provider search** (while *Provider search* is on, [below](#provider-search)): the web search a model provider runs itself.
- **The pages found** (either switch): read as text. Public `https` addresses only, checked before every request and again at connect time (no
  loopback, private, link-local, CGNAT or metadata address), at most 3 redirects each checked, 8 seconds and 1.5 MB per page,
  HTML or text only (a PDF is not read; its search snippet is used). No cookie, no referrer, a fixed `VenomResearch/1` User-Agent.
- **World Bank open data** (`api.worldbank.org`, no key): annual series by country, such as exchange rates, inflation, GDP,
  current account and trade.

### Provider search {#provider-search}

With *Provider search for research runs* on in Settings → Search, researchers also search through the model providers the
organisation has a key for (its own key first, else Venom's when "Use Venom's keys" allows it; never on a sovereign-only org):

| Provider | How | What comes back |
|---|---|---|
| OpenAI | Responses API, tool `web_search`, on gpt-5.4-mini | the pages the answer cites, with the sentence each backs, and the other pages consulted |
| Anthropic | Messages API, server tool `web_search_20250305` (3 searches at most), on Claude Haiku | the pages cited, with the page's own quoted words, and the other results |
| Model Studio (Qwen) | its Responses API (`compatible-mode/v1/responses`), tool `web_search`, on qwen3.8-flash | as OpenAI |
| Z.ai | its Web Search API (`/paas/v4/web_search`, engine `search-prime`) | results with their text and date |

The gear's own providers are asked first (`normal` and `eco`: OpenAI; `qwen`: Model Studio; `china`: Model Studio, then Z.ai);
a gear whose provider has no web search still researches through another keyed provider, or Venom Search. With Venom Search on
too, every query goes to Venom Search and the first two of each round also to a provider; with only provider search, every
query goes to a provider. The research queries go to that provider, which is why it is off until an owner or admin turns it
on. Each call is booked in Requests and Usage under the model `provider-search` (path `/v1/search`, the provider and whose key
in `upstream`), at the provider's search fee plus the tokens. The plan card lists every engine a run used with its search count.

**When research is off**, nothing leaves Venom. The plan card says so and links Settings, Search, where an owner or admin turns
it on. The run goes on with the model's own knowledge: the report opens with a "Not researched" warning and every figure is
an unverified estimate.

## Long runs {#continuation}

A deep run takes longer than one function invocation. Every step's output is kept in `studio_research_runs` as it finishes,
and a driver holds the run's lease while it works. When an invocation ends (its time is up, or a deploy replaced it), the next
driver carries the run on from its last finished step: the chat's own event stream as you watch it, and the `studio-research`
cron every minute. The chat stays busy until the run ends; **Stop** cancels it, and what it built so far stays. A run that
goes far past its wall time is ended with a message.

## For MCP clients {#mcp}

The same pipeline is three [Studio tools](/docs/studio/agents.md), with a REST twin under `/api/v1/studio/research`:

| Tool | REST | What |
|---|---|---|
| `studio_research_start` | `POST /studio/research` | Start a run: `prompt`, optional `kind`, `intensity` (`standard`, `deep`), `max_agents`, `gear`, `title`. Answers the run id at once. |
| `studio_research_get` | `GET /studio/research/{id}`, `GET /studio/research` | The plan card (goals, steps, researchers, sources, budget used, the artifact) and the answer when done; without an id, your recent runs. |
| `studio_research_cancel` | `POST /studio/research/{id}/cancel` | Cancel a running run. |

A run belongs to the member who started it (a personal key or an OAuth grant); a shared key bound to an agent cannot start one,
since the model calls run under the member's agents key. Poll `studio_research_get` about once a minute.
