# Valyu

> Search the web and specialist collections together: academic papers, SEC filings, patents, clinical trials, genomics and market data. Get ranked sources, read the pages behind them, ask for a cited answer, or commission a full research report with charts and spreadsheets.

App · AI Search & Memory · 13 actions. Web page: https://docs.lodol.com/docs/integrations/valyu

## Actions

### Add to a running report

Send an extra instruction to a report that is still researching, to point it somewhere the early findings suggest. Valyu takes it up until the writing begins.

**Inputs**

- Report (`report_id`, text, required): The report's id, as given back by 'Start a research report'.
- Extra instruction (`instruction`, text, required): What to add or change, such as 'Also compare the safety profiles across every trial'.

**Outputs**

- `accepted` (true/false): Whether the instruction was taken up.
- `message` (text): What Valyu said about it.
- `report_id` (text): The report's id.

**Example output**

```json
{
  "accepted": true,
  "message": "Task updated successfully",
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### Answer a question

Ask a question and get a written answer back, along with the sources it was drawn from. Valyu searches, reads and writes in one step, which takes about half a minute.

**Inputs**

- Question (`query`, text, required): The question to answer, such as 'Which GLP-1 drugs have FDA approval for adolescents, and when were they approved?'.
- Where to look (`search_type`, text): Which half of Valyu's catalogue to draw on. One of: `all` (Everything Valyu can reach (recommended)), `web` (The open web only), `proprietary` (Specialist sources only), `news` (News only). Default: `all`.
- Sources to search (`included_sources`, list): Pick the subject groups or individual datasets to search. Leave empty and Valyu chooses the best sources for the question itself. You can also type a website, such as nature.com, to search only that site.
- Sources to leave out (`excluded_sources`, list): Datasets or websites to skip, such as reddit.com. Subject groups cannot be excluded, so narrow 'Sources to search' instead of excluding a whole group.
- How to answer (`instructions`, text): How the answer should be written and what it should weigh, such as 'Answer as a regulatory analyst and cite every claim'.
- Favour results from (`country_code`, text): Bias web results towards one country. Leave empty to search everywhere. One of: `ALL` (Anywhere), `AR` (Argentina), `AU` (Australia), `AT` (Austria), `BE` (Belgium), `BR` (Brazil), `CA` (Canada), `CL` (Chile), `DK` (Denmark), `FI` (Finland), and 27 more.
- Published on or after (`start_date`, date): Only use sources published on or after this date.
- Published on or before (`end_date`, date): Only use sources published on or before this date.
- Favour speed over depth (`fast_mode`, true/false): Search more widely in fewer rounds. Quicker, and less thorough on a question that needs following up. Default: `false`.

**Outputs**

- `answer` (text): The written answer.
- `cost_dollars` (number): What this answer cost, in US dollars.
- `source_count` (number): How many sources were used.
- `sources` (list): The sources the answer was drawn from.

**Example output**

```json
{
  "answer": "Three GLP-1 receptor agonists hold FDA approval for...",
  "cost_dollars": 0.13,
  "source_count": 1,
  "sources": [
    {
      "title": "FDA approves treatment for adolescents",
      "url": "https://www.fda.gov/news-events/example"
    }
  ]
}
```

### Cancel a research report

Stop a report that is queued or still researching. A report that has already finished cannot be cancelled.

**Inputs**

- Report (`report_id`, text, required): The report's id, as given back by 'Start a research report'.

**Outputs**

- `cancelled` (true/false): Whether the report was stopped.
- `message` (text): What Valyu said about it.
- `report_id` (text): The report's id.

**Example output**

```json
{
  "cancelled": true,
  "message": "Task cancelled successfully",
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### Delete a research report

Permanently delete a finished report and everything it produced: the text, its sources, the PDF and any files. A report that is still running has to be cancelled first.

**Inputs**

- Report (`report_id`, text, required): The report's id, as given back by 'Start a research report'.

**Outputs**

- `deleted` (true/false): Whether the report was deleted.
- `message` (text): What Valyu said about it.
- `report_id` (text): The report's id.

**Example output**

```json
{
  "deleted": true,
  "message": "Task deleted successfully",
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### Find a source

Describe the kind of data you need and get back the collections that hold it, best match first. Use the ids it returns under 'Sources to search'.

**Inputs**

- What kind of data (`query`, text, required): What you are after, in plain language, such as 'FDA drug labels' or 'insider share transactions'.
- How many to return (`limit`, number): The most sources to return, up to 100. From 1 to 100. Default: `20`.

**Outputs**

- `source_count` (number): How many datasets were returned.
- `sources` (list): The matching datasets.

**Example output**

```json
{
  "source_count": 1,
  "sources": [
    {
      "category": "healthcare",
      "id": "valyu/valyu-drug-labels",
      "name": "FDA Drug Labels",
      "relevance_score": 0.7969
    }
  ]
}
```

### Get a research report

Read a report back. While it is still working this returns how far along it is; once it has finished it returns the report itself, its sources and any files it produced. Check 'is_finished' to know which you have.

**Inputs**

- Report (`report_id`, text, required): The report's id, as given back by 'Start a research report'.

**Outputs**

- `completed_at` (text): When the report finished.
- `cost_dollars` (number): What the report cost, in US dollars.
- `error` (text): Why the report failed, if it did.
- `files` (list): The extra files the report produced.
- `images` (list): Charts and pictures made along the way.
- `is_finished` (true/false): True once the report has stopped working.
- `pdf_url` (text): A link to the PDF, if one was asked for.
- `query` (text): The brief the report was given.
- `report` (text): The finished report, once there is one.
- `report_id` (text): The report's id.
- `source_count` (number): How many sources the report cited.
- `sources` (list): Everything the report cited.
- `status` (text): queued, running, completed, failed or cancelled.
- `steps_done` (number): Steps completed so far, while it is running.
- `steps_total` (number): Steps the report expects to take.

**Example output**

```json
{
  "completed_at": "2026-06-15T10:42:00.000Z",
  "cost_dollars": 0.5,
  "error": null,
  "files": [],
  "images": [],
  "is_finished": true,
  "pdf_url": "https://storage.valyu.ai/pdfs/a1b2c3d4.pdf",
  "query": "Compare European grocery delivery unit economics",
  "report": "# Findings\n\nAcross the five companies...",
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source_count": 1,
  "sources": [
    {
      "title": "Annual report 2025",
      "url": "https://example.com/annual-report"
    }
  ],
  "status": "completed",
  "steps_done": 15,
  "steps_total": 15
}
```

### List available sources

List the specialist collections this account can search, with what each one covers, how often it updates and what it costs.

**Inputs**

- Subject area (`category`, text): Narrow the list to one subject area. Leave empty for everything.

**Outputs**

- `source_count` (number): How many datasets were returned.
- `sources` (list): The matching datasets.

**Example output**

```json
{
  "source_count": 1,
  "sources": [
    {
      "category": "research",
      "description": "Preprints in physics, mathematics and more.",
      "id": "valyu/valyu-arxiv",
      "name": "arXiv",
      "update_frequency": "daily"
    }
  ]
}
```

### List research reports

List the reports this connection has commissioned, newest first, with the state each one is in.

**Inputs**

- How many to list (`limit`, number): The most reports to return, up to 100. From 1 to 100. Default: `20`.

**Outputs**

- `report_count` (number): How many reports were returned.
- `reports` (list): One entry per report.

**Example output**

```json
{
  "report_count": 1,
  "reports": [
    {
      "created_at": "2026-06-15T11:00:00.000Z",
      "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "query": "Quantum computing market analysis",
      "status": "completed"
    }
  ]
}
```

### List subject areas

List the subject areas Valyu groups its collections into, with how many collections sit in each one.

**Inputs**: None.

**Outputs**

- `categories` (list): One entry per subject area.
- `category_count` (number): How many subject areas there are.

**Example output**

```json
{
  "categories": [
    {
      "dataset_count": 8,
      "description": "Academic papers, preprints and articles.",
      "id": "research",
      "name": "Research"
    }
  ],
  "category_count": 1
}
```

### Read web pages

Pull the readable text out of up to ten web pages, with an optional summary of each one. Use it on the addresses a search returned, or on any page you already know.

**Inputs**

- Web page addresses (`urls`, list, required): The pages to read, up to ten. Paste one address per entry, or use the addresses from an earlier search step.
- Summarise each page (`summary`, text): Say what the summary should cover, such as 'the pricing and who it is for'. Leave empty to get the page text only.
- How much of each page (`response_length`, text): How much text to bring back from each page. One of: `short` (Short (about 25,000 characters each)), `medium` (Medium (about 50,000 characters each)), `large` (Long (about 100,000 characters each)), `max` (Everything there is). Default: `short`.
- How to load each page (`extract_effort`, text): Automatic suits almost every page. Choose 'In a full browser' for a page that builds itself after loading and comes back empty otherwise. One of: `auto` (Automatic (recommended)), `normal` (Plain and fast), `high` (In a full browser). Default: `auto`.
- Capture a picture of each page (`screenshot`, true/false): Also return an image of each page as it looked when it was read. Default: `false`.

**Outputs**

- `cost_dollars` (number): What this read cost, in US dollars.
- `failed_count` (number): How many pages could not be read.
- `page_count` (number): How many pages were read.
- `pages` (list): One entry per page that was read.

**Example output**

```json
{
  "cost_dollars": 0.002,
  "failed_count": 0,
  "page_count": 1,
  "pages": [
    {
      "content": "Quantum computing is a type of computation...",
      "length": 15420,
      "summary": "An overview of quantum computing.",
      "title": "Quantum computing",
      "url": "https://en.wikipedia.org/wiki/Quantum_computing"
    }
  ]
}
```

### Search for sources

Search the web and Valyu's specialist collections at once, and get back ranked sources with the relevant text already pulled out of each one.

**Inputs**

- What to look for (`query`, text, required): Describe what you want in plain language, such as 'phase 3 results for GLP-1 drugs in adolescents'. Search operators like site: and quotation marks are not needed and are not used.
- Where to look (`search_type`, text): Which half of Valyu's catalogue to read. Specialist sources are papers, filings, patents, trials and market data. One of: `all` (Everything Valyu can reach (recommended)), `web` (The open web only), `proprietary` (Specialist sources only), `news` (News only). Default: `all`.
- Number of sources (`max_num_results`, number): How many sources to return. Most accounts can ask for up to 20; a higher limit has to be enabled by Valyu. From 1 to 100. Default: `5`.
- Sources to search (`included_sources`, list): Pick the subject groups or individual datasets to search. Leave empty and Valyu chooses the best sources for the question itself. You can also type a website, such as nature.com, to search only that site.
- Sources to leave out (`excluded_sources`, list): Datasets or websites to skip, such as reddit.com. Subject groups cannot be excluded, so narrow 'Sources to search' instead of excluding a whole group.
- What makes a source relevant (`instructions`, text): One or two sentences on what you are really after, used to rank the results. For example, 'prefer primary trial data over press coverage'.
- Minimum relevance (`relevance_threshold`, number): Drop anything scoring below this, from 0 to 1. Raise it towards 0.8 for fewer, closer matches. From 0 to 1. Default: `0.5`.
- How much of each source (`response_length`, text): How much text to bring back from each source. Short is plenty for most workflows. One of: `short` (Short (about 25,000 characters each)), `medium` (Medium (about 50,000 characters each)), `large` (Long (about 100,000 characters each)), `max` (Everything there is). Default: `short`.
- Favour results from (`country_code`, text): Bias web results towards one country. Leave empty to search everywhere. One of: `ALL` (Anywhere), `AR` (Argentina), `AU` (Australia), `AT` (Austria), `BE` (Belgium), `BR` (Brazil), `CA` (Canada), `CL` (Chile), `DK` (Denmark), `FI` (Finland), and 27 more.
- Published on or after (`start_date`, date): Only use sources published on or after this date.
- Published on or before (`end_date`, date): Only use sources published on or before this date.
- Include PubMed abstracts (`include_abstracts`, true/false): Search every PubMed abstract, not only the papers with full text available. Widens medical results and changes nothing elsewhere. Default: `false`.
- Favour speed over quality (`fast_mode`, true/false): Answer in about a second by skipping the reranking step. This searches the web only, and ignores 'What makes a source relevant'. Default: `false`.

**Outputs**

- `cost_dollars` (number): What this search cost, in US dollars.
- `result_count` (number): How many sources were returned.
- `results` (list): The sources that matched, best first.
- `results_by_source` (object): How many came from the web and how many from datasets.

**Example output**

```json
{
  "cost_dollars": 0.0005,
  "result_count": 1,
  "results": [
    {
      "content": "We present a novel approach to topological...",
      "id": "valyu/valyu-arxiv/2401.12345",
      "publication_date": "2024-01-15",
      "relevance_score": 0.89,
      "source": "valyu/valyu-arxiv",
      "title": "Advances in Topological Quantum Computing",
      "url": "https://arxiv.org/abs/2401.12345"
    }
  ],
  "results_by_source": {
    "proprietary": 1,
    "web": 0
  }
}
```

### Share a research report

Put a report behind a link anyone can open, or take it back to private. Only the account that commissioned it can change this.

**Inputs**

- Report (`report_id`, text, required): The report's id, as given back by 'Start a research report'.
- Who can see it (`visibility`, text, required): Sharing a report lets anyone with the link read it without signing in to Valyu. One of: `shared` (Anyone with the link), `private` (Only this account).

**Outputs**

- `is_shared` (true/false): True when anyone with the link can read it.
- `message` (text): What Valyu said about it.
- `report_id` (text): The report's id.

**Example output**

```json
{
  "is_shared": true,
  "message": "Public flag updated",
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### Start a research report

Hand Valyu a research brief and it writes a cited report, searching and cross-checking on its own. The report is not ready when this step finishes: it takes from five minutes to two hours depending on the depth, so follow this with a Wait step and 'Get a research report'.

**Inputs**

- What to research (`query`, text, required): The brief, in as much detail as you like. For example, 'Compare the unit economics of the top five European grocery delivery companies since 2023'.
- How deep to go (`depth`, text): Deeper reports search more widely and cost more. The price is charged to your Valyu account. One of: `fast` (Quick (about 5 minutes, about $0.10)), `standard` (Standard (10 to 20 minutes, about $0.50)), `heavy` (Deep (30 to 45 minutes, about $2.50)), `max` (Exhaustive (up to 2 hours, about $15.00)). Default: `standard`.
- How to research it (`research_strategy`, text): How to go about the work, such as 'Start from company filings, then check the figures against analyst coverage'. Leave empty to let Valyu decide.
- How the report should read (`report_format`, text): The shape you want, such as 'A two-page summary with a comparison table and no preamble'.
- Files to produce as well (`deliverables`, list): Describe each extra file in plain English and name the format you want, such as 'An Excel sheet with one row per company and its margin by year'. Up to ten.
- Also produce a PDF (`include_pdf`, true/false): Return a formatted PDF of the report alongside the text. Default: `false`.
- Extra abilities (`tools`, list): What the researcher may do beyond reading. Choose nothing to let Valyu decide; choose anything and it uses exactly what you pick. Screenshots, code and browsing each add a small charge. One or more of: `charts` (Draw charts in the report), `code_execution` (Run calculations on the figures it finds), `screenshots` (Capture pictures of pages), `browser_use` (Browse sites that need clicking through).
- Pages to start from (`urls`, list): Addresses to read as part of the research, up to ten. Valyu searches for more on its own.
- Build on earlier reports (`previous_reports`, list): The ids of up to three earlier reports to use as background, so a recurring report picks up where the last one left off.
- Where to look (`search_type`, text): Which half of Valyu's catalogue to research from. One of: `all` (Everything Valyu can reach (recommended)), `web` (The open web only), `proprietary` (Specialist sources only). Default: `all`.
- Sources to search (`included_sources`, list): Pick the subject groups or individual datasets to search. Leave empty and Valyu chooses the best sources for the question itself. You can also type a website, such as nature.com, to search only that site.
- Sources to leave out (`excluded_sources`, list): Datasets or websites to skip, such as reddit.com. Subject groups cannot be excluded, so narrow 'Sources to search' instead of excluding a whole group.
- Favour results from (`country_code`, text): Bias web results towards one country. Leave empty to search everywhere. One of: `ALL` (Anywhere), `AR` (Argentina), `AU` (Australia), `AT` (Austria), `BE` (Belgium), `BR` (Brazil), `CA` (Canada), `CL` (Chile), `DK` (Denmark), `FI` (Finland), and 27 more.
- Published on or after (`start_date`, date): Only use sources published on or after this date.
- Published on or before (`end_date`, date): Only use sources published on or before this date.

**Outputs**

- `created_at` (text): When the report was commissioned.
- `depth` (text): The depth the report is running at.
- `is_finished` (true/false): Always false here. A report has only just begun.
- `report_id` (text): The id to read the report back with.
- `status` (text): Where the report is up to: queued or running.

**Example output**

```json
{
  "created_at": "2026-06-15T10:30:00.000Z",
  "depth": "standard",
  "is_finished": false,
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running"
}
```