> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Search API Quickstart - Get Started in 5 Minutes

> Integrate Valyu's search API for AI agents in minutes. Access web search and 36+ proprietary data sources including PubMed, SEC filings, clinical trials, and patents with Python, JavaScript, or REST API.

<Steps>
  <Step title="Get your free Valyu API key">
    Go to the [Valyu Platform](https://platform.valyu.ai) and sign in (or create an account). Copy an API key from your dashboard.

    <Card title="Get your free API key" icon="key" href="https://platform.valyu.ai/user/account/apikeys" arrow="true" horizontal>
      You get over 1000 free query retrievals. No credit card required.
    </Card>

    <Note icon="discord">
      Join the Valyu community on{" "}
      <a href="https://discord.gg/umtmSsppRY">Discord</a> for help and release previews.
    </Note>
  </Step>

  <Step title="Install Valyu">
    Install the SDK for your language:

    <CodeGroup>
      ```python Python theme={null}
      pip install valyu
      ```

      ```typescript JavaScript theme={null}
      npm install valyu-js
      ```
    </CodeGroup>
  </Step>

  <Step title="Start searching">
    ### Basic Search

    Run your first search in a few lines of code:

    <CodeGroup>
      ```python Python theme={null}
      from valyu import Valyu

      valyu = Valyu("your-api-key-here")
      response = valyu.search("What is quantum computing?")

      for result in response.results:
          print(f"Title: {result.title}")
          print(f"Content preview: {result.content[:200]}...")
          print(f"URL: {result.url}")

      ```

      ```javascript JavaScript theme={null}
      import { Valyu } from "valyu-js";

      const valyu = new Valyu("your-api-key-here");
      const response = await valyu.search("What is quantum computing?");

      response.results.forEach((result) => {
          console.log(`Title: ${result.title}`);
          console.log(`Content preview: ${result.content.substring(0, 200)}...`);
          console.log(`URL: ${result.url}`);
      });
      ```

      ```curl curl theme={null}
      Pass one of the commands below to your terminal to make an API request
      ```
    </CodeGroup>

    ### Advanced Search

    Add parameters to improve or filter results:

    <CodeGroup>
      ```python Python theme={null}
      from valyu import Valyu

      valyu = Valyu("your-api-key-here")
      response = valyu.search(
          "Implementation details of agentic search-enhanced large reasoning models",
          search_type="proprietary",
          max_num_results=10,
          relevance_threshold=0.5,
          category="agentic retrieval-augmented generation",
          included_sources=["valyu/valyu-arxiv"],
          is_tool_call=True
      )

      for result in response.results:
          print(f" Title: {result.title}")
          print(f" URL: {result.url}")
          print(f" Content Preview: {result.content[:300]}...")

      ```

      ```javascript JavaScript theme={null}
      import { Valyu } from "valyu-js";

      const valyu = new Valyu("your-api-key-here");
      const response = await valyu.search(
        "Implementation details of agentic search-enhanced large reasoning models",
        {
          searchType: "proprietary",
          maxNumResults: 10,
          maxPrice: 30,
          relevanceThreshold: 0.5,
          category: "agentic retrieval-augmented generation",
          includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
          isToolCall: true
        }
      );

      response.results.forEach((result) => {
          console.log(`  Title: ${result.title}`);
          console.log(`  URL: ${result.url}`);
          console.log(`  Content Preview: ${result.content.substring(0, 300)}...`);
      });
      ```

      ```bash cURL theme={null}
      curl --request POST \
          --url https://api.valyu.ai/v1/search \
          --header 'accept: application/json' \
          --header 'content-type: application/json' \
          --header "x-api-key: ${VALYU_API_KEY}" \
          --data '
      {
        "query": "What is quantum computing?",
        "search_type": "proprietary",
        "max_num_results": 10,
        "relevance_threshold": 0.5,
        "category": "agentic retrieval-augmented generation",
        "included_sources": ["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
        "is_tool_call": true
      }'
      ```
    </CodeGroup>

    <Note>
      For more details, see the
      <a href="/search/quickstart">Search Guide</a> and the
      <a href="/api-reference/endpoint/search">Search API reference</a>.
    </Note>

    ## Content Extraction

    Turn any web page into clean markdown (or structured data):

    <CodeGroup>
      ```python Python theme={null}
      from valyu import Valyu

      valyu = Valyu() # Uses VALYU_API_KEY from env

      data = valyu.contents(
          urls=[
              "https://en.wikipedia.org/wiki/Artificial_intelligence",
          ],
          response_length="medium",
          extract_effort="auto",
      )
      print(data["results"][0]["content"][:500])

      ```

      ```javascript JavaScript theme={null}
      import { Valyu } from "valyu-js";

      const valyu = new Valyu(); // Uses VALYU_API_KEY from env

      const data = await valyu.contents({
        urls: [
          "https://en.wikipedia.org/wiki/Artificial_intelligence",
        ],
        responseLength: "medium",
        extractEffort: "auto",
      });
      console.log(data.results[0].content.slice(0, 500));
      ```

      ```bash cURL theme={null}
      curl -X POST https://api.valyu.ai/v1/contents \
        -H "content-type: application/json" \
        -H "x-api-key: $VALYU_API_KEY" \
        -d '{
          "urls": [
            "https://en.wikipedia.org/wiki/Artificial_intelligence"
          ],
          "response_length": "medium",
          "extract_effort": "auto"
        }'
      ```
    </CodeGroup>

    <Note>
      For structured extraction with JSON Schemas or AI summaries, see the
      <a href="/guides/content-extraction">Content Extraction Guide</a> and the
      <a href="/api-reference/endpoint/contents">Contents API reference</a>.
    </Note>

    ## AI-Powered Answers

    Get intelligent responses that combine search with AI processing:

    <CodeGroup>
      ```python Python theme={null}
      from valyu import Valyu

      valyu = Valyu() # Uses VALYU_API_KEY from env

      data = valyu.answer(
          query="latest developments in quantum computing",
      )
      print(data["contents"])

      ```

      ```javascript JavaScript theme={null}
      import { Valyu } from "valyu-js";

      const valyu = new Valyu(); // Uses VALYU_API_KEY from env

      const data = await valyu.answer({
        query: "latest developments in quantum computing",
      });
      console.log(data.contents);
      ```

      ```bash cURL theme={null}
      curl -X POST https://api.valyu.ai/v1/answer \
        -H "content-type: application/json" \
        -H "x-api-key: $VALYU_API_KEY" \
        -d '{
          "query": "latest developments in quantum computing"
        }'
      ```
    </CodeGroup>

    <Note>
      For structured responses or custom AI instructions, see the
      <a href="/guides/answer-api">Answer API Guide</a> and the
      <a href="/api-reference/endpoint/answer">Answer API reference</a>.
    </Note>

    ## Deep Research

    For comprehensive, multi-step research that generates detailed reports:

    <CodeGroup>
      ```python Python theme={null}
      from valyu import Valyu

      valyu = Valyu() # Uses VALYU_API_KEY from env

      # Create a research task
      task = valyu.deepresearch.create(
          input="Analyze the competitive landscape of cloud computing in 2024",
          model="standard" 
      )

      # Wait for completion
      result = valyu.deepresearch.wait(task.deepresearch_id)

      print(result.output)  # Full research report
      print(f"Sources: {len(result.sources)}")
      print(f"Cost: ${result.cost}")
      ```

      ```javascript JavaScript theme={null}
      import { Valyu } from "valyu-js";

      const valyu = new Valyu(); // Uses VALYU_API_KEY from env

      // Create a research task
      const task = await valyu.deepresearch.create({
        input: "Analyze the competitive landscape of cloud computing in 2024",
        model: "standard"
      });

      // Wait for completion
      const result = await valyu.deepresearch.wait(task.deepresearch_id);

      console.log(result.output);  // Full research report
      console.log(`Sources: ${result.sources?.length}`);
      console.log(`Cost: $${result.cost}`);
      ```

      ```bash cURL theme={null}
      # Create task
      curl -X POST https://api.valyu.ai/v1/deepresearch/tasks \
        -H "content-type: application/json" \
        -H "x-api-key: $VALYU_API_KEY" \
        -d '{
          "input": "Analyze the competitive landscape of cloud computing in 2024",
          "model": "standard"
        }'

      # Poll for status (replace TASK_ID)
      curl https://api.valyu.ai/v1/deepresearch/tasks/TASK_ID/status \
        -H "x-api-key: $VALYU_API_KEY"
      ```
    </CodeGroup>

    <Note>
      DeepResearch runs asynchronously and can take several minutes. For complex research, use `mode: "heavy"`.
      See the <a href="/guides/deepresearch">DeepResearch Guide</a> for webhooks, structured output, and more.
    </Note>
  </Step>
</Steps>

***

## Use Cases

### Academic Research

Search millions of papers with full-text retrieval:

<CodeGroup>
  ```python Python theme={null}
  response = valyu.search(
      "Extending context window of large language models via positional interpolation",
      search_type="proprietary",
      max_num_results=5,
      included_sources=["valyu/valyu-arxiv", "valyu/valyu-pubmed"]
  )

  for result in response.results:
      print(f" Title: {result.title}")
      print(f" Authors: {', '.join(result.authors) if hasattr(result, 'authors') else 'N/A'}")
      print(f" Publication Date: {getattr(result, 'publication_date', 'N/A')}")
      print(f" DOI: {getattr(result, 'doi', 'N/A')}")
      print(f" Citation: {getattr(result, 'citation', 'N/A')}")
      print(f" Citation Count: {getattr(result, 'citation_count', 'N/A')}")
      print(f" Content Preview: {result.content[:200]}...")

  ```

  ```javascript JavaScript theme={null}
  const response = await valyu.search(
      "Extending context window of large language models via positional interpolation",
      {
          searchType: "proprietary",
          maxNumResults: 5,
          maxPrice: 30,
          includedSources: ["valyu/valyu-arxiv"]
      }
  );

  response.results.forEach((result) => {
      console.log(`  Title: ${result.title}`);
      console.log(`  Authors: ${result.authors ? result.authors.join(', ') : 'N/A'}`);
      console.log(`  Publication Date: ${result.publication_date || 'N/A'}`);
      console.log(`  DOI: ${result.doi || 'N/A'}`);
      console.log(`  Citation: ${result.citation || 'N/A'}`);
      console.log(`  Citation Count: ${result.citation_count || 'N/A'}`);
      console.log(`  Content Preview: ${result.content.substring(0, 200)}...`);
  });
  ```
</CodeGroup>

Example response:

```json theme={null}
{
  "success": true,
  "error": "",
  "tx_id": "tx_55e65c6f-3607-4ebe-892b-e964b9c72a8d",
  "query": "Extending context window of large language models via positional interpolation",
  "results": [
    {
      "id": "55e65c6f-3607-4ebe-892b-e964b9c72a8d:2306.15595:1",
      "title": "Extending Context Window of Large Language Models via Positional Interpolation",
      "url": "https://arxiv.org/abs/2306.15595?utm_source=valyu.ai&utm_medium=referral",
      "content": "#### 2.3 PROPOSED APPROACH: POSITION INTERPOLATION (PI)\n\n#### 2.1 BACKGROUND: ROTARY POSITION EMBEDDING (ROPE)\n\nTransformer models require explicit positional information...",
      "source": "valyu/valyu-arxiv",
      "length": 593,
      "publication_date": "2023-01-01",
      "doi": "https://doi.org/10.48550/arxiv.2306.15595",
      "citation": "Shouyuan Chen et al. (2023). Extending Context Window of Large Language Models via Positional Interpolation.",
      "citation_count": 25,
      "authors": [
        "Shouyuan Chen",
        "S.H. Wong",
        "Liangjian Chen",
        "Yuandong Tian"
      ],
      "price": 0.0005,
      "data_type": "unstructured",
      "source_type": "paper",
      "relevance_score": 0.8071867796187081
    }
  ],
  "results_by_source": {
    "proprietary": 1,
    "web": 0
  }
}
```

### Financial Market Data

Just ask in plain English:

<CodeGroup>
  ```python Python theme={null}
  response = valyu.search(
      "Pfizer stock price since COVID-19 outbreak",
      search_type="proprietary",
      max_num_results=1
  )

  for result in response.results:
      print(f" Title: {result.title}")
      print(f" Content Preview: {str(result.content)[:300]}...")
      if result.data_type == "structured" and isinstance(result.content, list):
          print(f" Sample Data Points: {len(result.content)} entries")
          for item in range(0, 3):
              print(f" {result.content[item]}")

  ```

  ```javascript JavaScript theme={null}
  const response = await valyu.search(
      "Pfizer stock price since COVID-19 outbreak",
      {
          searchType: "proprietary",
          maxNumResults: 1,
          maxPrice: 30
      }
  );

  response.results.forEach((result) => {
      console.log(`  Title: ${result.title}`);
      console.log(`  Content Preview: ${String(result.content).substring(0, 300)}...`);
      if (result.data_type === "structured" && Array.isArray(result.content)) {
          console.log(`  Sample Data Points: ${result.content.length} entries`);
          for (let i = 0; i < Math.min(3, result.content.length); i++) {
              console.log(`  ${JSON.stringify(result.content[i])}`);
          }
      }
  });
  ```
</CodeGroup>

Example response:

```json theme={null}
{
    "success": true,
    "error": "",
    "tx_id": "tx_6a2568cf-a3f4-4860-9b6e-96b35e398b7f",
    "query": "Price of TSLA today?",
    "results": [
      {
        "title": "Price of PFE every 1mo between 2020-01-01 00:00 and 2025-05-26 00:00",
        "url": "https://platform.valyu.ai/data-sources/valyu/valyu-stocks/characteristics",
        "content": [
          {
              "datetime": "2025-05-01 04:00:00",
              "open": 24,
              "high": 24,
              "low": 22,
              "close": 23,
              "volume": 78776482
          }
        ],
        "source": "valyu/valyu-stocks",
        "price": 0.006,
        "length": 8175,
        "data_type": "structured",
        "source_type": "data",
        "relevance_score": 0.6277149030411012
      }
    ],
    "results_by_source": {
        "proprietary": 1,
        "web": 0
    }
}
```

<Note>
  The search can interpret noisy queries like "\$\$\$\$\$ of larry and
  Sergey brins companie. on fr week commencing 5th hune on the 21st century"
  (which maps to "Google stock price for Friday June 5th, 2021").
</Note>

## Next Steps

<CardGroup cols={3}>
  <Card title="Python SDK" icon="python" href="/sdk/python-sdk">
    Python SDK documentation
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdk/typescript-sdk">
    TypeScript SDK documentation
  </Card>

  <Card title="DeepResearch Guide" icon="flask" href="/guides/deepresearch">
    Comprehensive async research
  </Card>

  <Card title="Tips and Tricks" icon="lightbulb" href="/search/tips-and-tricks">
    Get better results
  </Card>

  <Card title="Prompting Guide" icon="square-pen" href="/search/prompting">
    Write effective queries
  </Card>

  <Card title="MCP Integration" icon="robot" href="/integrations/mcp-server">
    Power your MCP agents
  </Card>
</CardGroup>