The Valyu SDK provides access to the following features:

  1. Deep Search - Search and retrieve relevant content from proprietary and public sources

​
Getting Started

Install the Valyu SDK

npm install valyu
# or
yarn add valyu

And then instantiate the Valyu client - you can obtain your API key here ($10 free credits cus we are legends)

import { Valyu } from "valyu";

// The SDK will automatically use VALYU_API_KEY from environment
const valyu = new Valyu();

// Alternatively, you can still pass it explicitly
const valyu = new Valyu("your-api-key-here");

​
Quick Start

Let’s see how to use the deep search feature with a simple example:

main.ts
import { Valyu } from "valyu";

// Initialize the client
const valyu = new Valyu();

// Search for information about a specific topic
const response = await valyu.search(
  "What are the benefits of renewable energy?",
  {
    searchType: "all", // Search both proprietary and web sources
    maxNumResults: 5, // Limit to top 5 results
    relevanceThreshold: 0.5, // Only return results with >50% relevance
    maxPrice: 20.0, // Maximum cost in dollars
    isToolCall: true, // true for AI agents/tools, false for direct user queries
  }
);

// Process the results
console.log(response);

​
Advanced Usage

Here’s an example using more v2 parameters for targeted searches:

// AI Agent making a search (tool call)
const financialResponse = await valyu.search(
  "Pfizer stock price since COVID-19 outbreak",
  {
    searchType: "proprietary",
    maxNumResults: 1,
    relevanceThreshold: 0.5,
    maxPrice: 30.0,
    isToolCall: true, // true: AI agent/tool is making this search
  }
);

// Direct user query (not through an AI agent)
const userResponse = await valyu.search(
  "What are the latest developments in quantum computing?",
  {
    searchType: "all",
    maxNumResults: 5,
    relevanceThreshold: 0.5,
    maxPrice: 30.0,
    isToolCall: false, // false: Direct user query, not through AI agent
  }
);

// Academic research with specific sources (AI agent)
const academicResponse = await valyu.search(
  "CRISPR gene editing safety studies",
  {
    searchType: "proprietary",
    maxNumResults: 8,
    relevanceThreshold: 0.8,
    maxPrice: 30.0,
    category: "biomedical research",
    includedSources: ["valyu/valyu-pubmed"],
    isToolCall: true, // true: Part of an AI agent workflow
  }
);

​
Input Parameters:

ParameterTypeDescriptionDefault
querystringThe input query to be processed.Required
searchTypeLiteral[‘all’, ‘proprietary’, ‘web’]Specifies the type of search to be performed. ‘all’ includes both proprietary and web sources, ‘proprietary’ searches over Valyu indices, and ‘web’ is just web search.”all”
maxNumResultsnumberThe maximum number of results to be returned (1-20).5
relevanceThresholdnumberThe minimum relevance score required for a result to be included (0.0-1.0).0.5
maxPricenumberMaximum cost in dollars for 1000 retrievals.30.0
isToolCallbooleanSet to true when called by AI agents/tools (optimized for LLM consumption). Set to false for direct user queries.true
categorystringNatural language category to guide search context (optional).undefined
includedSourcesstring[]List of specific datasets or URLs to search within (optional).undefined
startDatestringStart date for time filtering in YYYY-MM-DD format (optional).undefined
endDatestringEnd date for time filtering in YYYY-MM-DD format (optional).undefined

​
Example Response:

{
    "success": true,
    "error": "",
    "tx_id": "tx_4cce8eed-7864-42ec-b385-dee7d5b14936",
    "query": "What are agentic search-enhanced large reasoning models?",
    "results": [
        {
            "title": "2501.05366",
            "url": "https://arxiv.org/abs/2501.05366",
            "content": "# Search-o1: Agentic Search-Enhanced Large Reasoning Models...",
            "source": "valyu/valyu-arxiv",
            "price": 0.0005,
            "length": 17442,
            "image_url": {
                "_page_1_Figure_0.jpeg": "https://..."
            },
            "dataType": "unstructured",
            "relevanceScore": 0.77734375
        }
        // Additional results...
    ],
    "resultsBySource": {
        "web": 1,
        "proprietary": 4
    },
    "totalResults": 5,
    "totalCharacters": 81208
}

​
Output Parameters:

ParameterTypeDescription
successbooleanIndicates if the request was successful
errorstringError message if any
tx_idstringUnique transaction ID for the request
querystringThe processed query string
resultsarrayArray of result objects (see Results Object table below)
resultsBySourceobjectCount of results by source type (web/proprietary)
totalResultsnumberTotal number of results returned
totalCharactersnumberTotal number of characters in results

​
Results Object:

ParameterTypeDescription
idstringUnique identifier for the result (optional)
titlestringTitle of the result
urlstringURL of the source
contentstringThe actual text chunk of the result
sourcestringSource identifier (e.g., “valyu/valyu-arxiv”, “valyu/valyu-stocks-US”)
pricenumberCost of this specific text chunk in USD
lengthnumberCharacter length of the content
image_urlobjectMap of image identifiers to image URLs, can be used to render in frontend AI applications
dataTypestringType of data, either “unstructured” or “structured”. If structured (e.g. for stock data) it will be a string JSON object
sourceTypestringType of source (e.g., “paper”, “data”, “web”, “book”)
relevanceScorenumberRelevance score between 0 and 1
publicationDatestringPublication date in YYYY-MM-DD format (for source_type “paper” and “book”)
doistringDigital Object Identifier (for source_type “paper” and “book”)
citationstringFormatted citation string (for source_type “paper”)
citationCountnumberNumber of citations (for source_type “paper”)
authorsstring[]List of author names (for source_type “paper” and “book”)
referencesstringReferences section content (for source_type “paper” and “book”)

For detailed documentation on each feature, please refer to their respective pages: