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.

Actions

Action	What it does
Add to a running report	Send an extra instruction to a report that is still researching, to point it somewhere the early findings suggest.
Answer a question	Ask a question and get a written answer back, along with the sources it was drawn from.
Cancel a research report	Stop a report that is queued or still researching.
Delete a research report	Permanently delete a finished report and everything it produced: the text, its sources, the PDF and any files.
Find a source	Describe the kind of data you need and get back the collections that hold it, best match first.
Get a research report	Read a report back.
List available sources	List the specialist collections this account can search, with what each one covers, how often it updates and what it costs.
List research reports	List the reports this connection has commissioned, newest first, with the state each one is in.
List subject areas	List the subject areas Valyu groups its collections into, with how many collections sit in each one.
Read web pages	Pull the readable text out of up to ten web pages, with an optional summary of each one.
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.
Share a research report	Put a report behind a link anyone can open, or take it back to private.
Start a research report	Hand Valyu a research brief and it writes a cited report, searching and cross-checking on its own.

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

Reportreport_idtextRequired: The report's id, as given back by 'Start a research report'.
Extra instructioninstructiontextRequired: What to add or change, such as 'Also compare the safety profiles across every trial'.

Outputs

acceptedtrue/false: Whether the instruction was taken up.
messagetext: What Valyu said about it.
report_idtext: The report's id.

Example output

{
  "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

QuestionquerytextRequired: The question to answer, such as 'Which GLP-1 drugs have FDA approval for adolescents, and when were they approved?'.
Where to looksearch_typetext: 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 searchincluded_sourceslist: 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 outexcluded_sourceslist: 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 answerinstructionstext: How the answer should be written and what it should weigh, such as 'Answer as a regulatory analyst and cite every claim'.
Favour results fromcountry_codetext: 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 afterstart_datedate: Only use sources published on or after this date.
Published on or beforeend_datedate: Only use sources published on or before this date.
Favour speed over depthfast_modetrue/false: Search more widely in fewer rounds. Quicker, and less thorough on a question that needs following up.Default: false.

Outputs

answertext: The written answer.
cost_dollarsnumber: What this answer cost, in US dollars.
source_countnumber: How many sources were used.
sourceslist: The sources the answer was drawn from.

Example output

{
  "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

Reportreport_idtextRequired: The report's id, as given back by 'Start a research report'.

Outputs

cancelledtrue/false: Whether the report was stopped.
messagetext: What Valyu said about it.
report_idtext: The report's id.

Example output

{
  "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

Reportreport_idtextRequired: The report's id, as given back by 'Start a research report'.

Outputs

deletedtrue/false: Whether the report was deleted.
messagetext: What Valyu said about it.
report_idtext: The report's id.

Example output

{
  "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 dataquerytextRequired: What you are after, in plain language, such as 'FDA drug labels' or 'insider share transactions'.
How many to returnlimitnumber: The most sources to return, up to 100.From 1 to 100. Default: 20.

Outputs

source_countnumber: How many datasets were returned.
sourceslist: The matching datasets.

Example output

{
  "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

Reportreport_idtextRequired: The report's id, as given back by 'Start a research report'.

Outputs

completed_attext: When the report finished.
cost_dollarsnumber: What the report cost, in US dollars.
errortext: Why the report failed, if it did.
fileslist: The extra files the report produced.
imageslist: Charts and pictures made along the way.
is_finishedtrue/false: True once the report has stopped working.
pdf_urltext: A link to the PDF, if one was asked for.
querytext: The brief the report was given.
reporttext: The finished report, once there is one.
report_idtext: The report's id.
source_countnumber: How many sources the report cited.
sourceslist: Everything the report cited.
statustext: queued, running, completed, failed or cancelled.
steps_donenumber: Steps completed so far, while it is running.
steps_totalnumber: Steps the report expects to take.

Example output

{
  "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 areacategorytext: Narrow the list to one subject area. Leave empty for everything.

Outputs

source_countnumber: How many datasets were returned.
sourceslist: The matching datasets.

Example output

{
  "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 listlimitnumber: The most reports to return, up to 100.From 1 to 100. Default: 20.

Outputs

report_countnumber: How many reports were returned.
reportslist: One entry per report.

Example output

{
  "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

categorieslist: One entry per subject area.
category_countnumber: How many subject areas there are.

Example output

{
  "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 addressesurlslistRequired: The pages to read, up to ten. Paste one address per entry, or use the addresses from an earlier search step.
Summarise each pagesummarytext: 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 pageresponse_lengthtext: 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 pageextract_efforttext: 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 pagescreenshottrue/false: Also return an image of each page as it looked when it was read.Default: false.

Outputs

cost_dollarsnumber: What this read cost, in US dollars.
failed_countnumber: How many pages could not be read.
page_countnumber: How many pages were read.
pageslist: One entry per page that was read.

Example output

{
  "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 forquerytextRequired: 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 looksearch_typetext: 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 sourcesmax_num_resultsnumber: 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 searchincluded_sourceslist: 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 outexcluded_sourceslist: 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 relevantinstructionstext: 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 relevancerelevance_thresholdnumber: 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 sourceresponse_lengthtext: 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 fromcountry_codetext: 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 afterstart_datedate: Only use sources published on or after this date.
Published on or beforeend_datedate: Only use sources published on or before this date.
Include PubMed abstractsinclude_abstractstrue/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 qualityfast_modetrue/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_dollarsnumber: What this search cost, in US dollars.
result_countnumber: How many sources were returned.
resultslist: The sources that matched, best first.
results_by_sourceobject: How many came from the web and how many from datasets.

Example output

{
  "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
  }
}

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

Reportreport_idtextRequired: The report's id, as given back by 'Start a research report'.
Who can see itvisibilitytextRequired: 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_sharedtrue/false: True when anyone with the link can read it.
messagetext: What Valyu said about it.
report_idtext: The report's id.

Example output

{
  "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 researchquerytextRequired: 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 godepthtext: 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 itresearch_strategytext: 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 readreport_formattext: The shape you want, such as 'A two-page summary with a comparison table and no preamble'.
Files to produce as welldeliverableslist: 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 PDFinclude_pdftrue/false: Return a formatted PDF of the report alongside the text.Default: false.
Extra abilitiestoolslist: 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 fromurlslist: Addresses to read as part of the research, up to ten. Valyu searches for more on its own.
Build on earlier reportsprevious_reportslist: 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 looksearch_typetext: 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 searchincluded_sourceslist: 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 outexcluded_sourceslist: 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 fromcountry_codetext: 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 afterstart_datedate: Only use sources published on or after this date.
Published on or beforeend_datedate: Only use sources published on or before this date.

Outputs

created_attext: When the report was commissioned.
depthtext: The depth the report is running at.
is_finishedtrue/false: Always false here. A report has only just begun.
report_idtext: The id to read the report back with.
statustext: Where the report is up to: queued or running.

Example output

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

ActionsCopy Anchor Link

Add to a running reportCopy Anchor Link

Inputs

Outputs

Answer a questionCopy Anchor Link

Inputs

Outputs

Cancel a research reportCopy Anchor Link

Inputs

Outputs

Delete a research reportCopy Anchor Link

Inputs

Outputs

Find a sourceCopy Anchor Link

Inputs

Outputs

Get a research reportCopy Anchor Link

Inputs

Outputs

List available sourcesCopy Anchor Link

Inputs

Outputs

List research reportsCopy Anchor Link

Inputs

Outputs

List subject areasCopy Anchor Link

Inputs

Outputs

Read web pagesCopy Anchor Link

Inputs

Outputs

Search for sourcesCopy Anchor Link

Inputs

Outputs

Share a research reportCopy Anchor Link

Inputs

Outputs

Start a research reportCopy Anchor Link

Inputs

Outputs

On this page

Actions

Add to a running report

Answer a question

Cancel a research report

Delete a research report

Find a source

Get a research report

List available sources

List research reports

List subject areas

Read web pages

Search for sources

Share a research report

Start a research report