> ## 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.

# Source Filtering

> Control which domains, datasets, and sources are included, excluded, or soft-ranked in search results

Control exactly which sources your search uses. Focus on trusted domains, access specific datasets, exclude unreliable sources, or soft-rank results toward preferred domains.

<Note>
  Source filters accept **domains**, **URLs**, **dataset names**, **specific paths**, or **collections**.
</Note>

<Tip>
  **Save time with Collections!** If you use the same source combinations frequently, create a [Collection](/search/filtering/collections) to bundle them and reference by name.
</Tip>

## What You Can Do

* **Target authoritative sources** - Focus on trusted domains and academic datasets
* **Block unreliable content** - Exclude low-quality or biased sources
* **Soft-rank by domain** - Boost or demote sources without hard filtering
* **Access specific datasets** - Search Valyu's proprietary collections
* **Improve result quality** - Get more relevant, higher-quality information

## Parameters

<CardGroup cols={3}>
  <Card title="included_sources" icon="circle-check">
    **Type**: Array of strings

    Only search within these sources. Can include domains, URLs, or dataset names.

    *Example*: `["arxiv.org", "valyu/valyu-pubmed"]`
  </Card>

  <Card title="excluded_sources" icon="circle-x">
    **Type**: Array of strings

    Exclude these sources from results. Same formats as included\_sources.

    *Example*: `["example.com", "example.org"]`
  </Card>

  <Card title="source_biases" icon="sliders">
    **Type**: Object (domain → integer)

    Soft-rank sources from **-5** (strong demotion) to **+5** (strong boost) without hard filtering.

    *Example*: `{"nasa.gov": 5, "example.com": -3}`
  </Card>
</CardGroup>

<Note>
  If both `included_sources` and `excluded_sources` are provided, `included_sources` takes priority.
</Note>

<Tip>
  **When to use `source_biases` vs hard filters:** Use `included_sources`/`excluded_sources` when you need strict control over which sources appear. Use `source_biases` when you want to influence ranking — boosting authoritative domains or demoting low-quality ones — while still allowing all sources to appear if they're highly relevant.
</Tip>

## Source Formats

| **Format**        | **Example**                     | **What It Does**                                                                 |
| ----------------- | ------------------------------- | -------------------------------------------------------------------------------- |
| **Domain**        | `"arxiv.org"`                   | Includes/excludes entire domain                                                  |
| **Base URL**      | `"https://docs.aws.amazon.com"` | Includes/excludes entire site                                                    |
| **Specific Path** | `"nasa.gov/news"`               | Targets only that path                                                           |
| **Dataset Name**  | `"valyu/valyu-arxiv"`           | Searches Valyu's [proprietary datasets](https://platform.valyu.ai/data-sources)  |
| **Collection**    | `"collection:my-sources"`       | Expands to all sources in your [saved collection](/search/filtering/collections) |

<Warning>
  **Path Specificity**: When using paths (e.g., `"valyu.ai/blog"`), only that exact path is affected. For entire domains, use just the domain name.
</Warning>

## Examples

### Academic Sources

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "quantum computing error correction",
      included_sources=[
          "valyu/valyu-arxiv",
          "valyu/valyu-pubmed",
          "valyu/valyu-biorxiv",
          "valyu/valyu-medrxiv"
      ],
      search_type="all"
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "quantum computing error correction",
    {
      includedSources: [
        'valyu/valyu-arxiv',
        'valyu/valyu-pubmed',
        'valyu/valyu-biorxiv',
        'valyu/valyu-medrxiv'
      ],
      searchType: 'all'
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "quantum computing error correction",
      "included_sources": [
        "valyu/valyu-arxiv",
        "valyu/valyu-pubmed",
        "valyu/valyu-biorxiv",
        "valyu/valyu-medrxiv"
      ],
      "search_type": "all"
    }'
  ```
</CodeGroup>

### Exclude Non-Government Sources

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "artificial intelligence safety research",
      excluded_sources=[
          "example.com",
          "example.org",
          "example.net"
      ]
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "artificial intelligence safety research",
    {
      excludedSources: [
        'example.com',
        'example.org',
        'example.net'
      ]
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "artificial intelligence safety research",
      "excluded_sources": [
        "example.com",
        "example.org",
        "example.net"
      ]
    }'
  ```
</CodeGroup>

### Official Documentation

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "React server components best practices",
      included_sources=[
          "https://react.dev/",
          "https://nextjs.org/docs",
          "https://docs.aws.amazon.com/",
          "developer.mozilla.org"
      ]
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "React server components best practices",
    {
      includedSources: [
        'https://react.dev/',
        'https://nextjs.org/docs',
        'https://docs.aws.amazon.com/',
        'developer.mozilla.org'
      ]
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "React server components best practices",
      "included_sources": [
        "https://react.dev/",
        "https://nextjs.org/docs", 
        "https://docs.aws.amazon.com/",
        "developer.mozilla.org"
      ]
    }'
  ```
</CodeGroup>

## Use Cases

### Financial Research

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "cryptocurrency regulation impact banking sector",
      included_sources=[
          "federalreserve.gov",
          "sec.gov", 
          "sec.gov/cgi-bin/browse-edgar",
          "treasury.gov",
          "imf.org"
      ],
      max_num_results=15
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "cryptocurrency regulation impact banking sector",
    {
      includedSources: [
        'federalreserve.gov',
        'sec.gov',
        'sec.gov/cgi-bin/browse-edgar',
        'treasury.gov',
        'imf.org'
      ],
      maxNumResults: 15
    }
  );
  ```
</CodeGroup>

### Medical Research

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "immunotherapy cancer treatment efficacy",
      included_sources=[
          "valyu/valyu-pubmed",
          "valyu/valyu-clinical-trials",
          "valyu/valyu-drug-labels",
          "valyu/valyu-medrxiv"
      ],
      search_type="proprietary"
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "immunotherapy cancer treatment efficacy",
    {
      includedSources: [
        'valyu/valyu-pubmed',
        'valyu/valyu-clinical-trials',
        'valyu/valyu-drug-labels',
        'valyu/valyu-medrxiv',
      ],
      searchType: 'proprietary'
    }
  );
  ```
</CodeGroup>

### Technical Documentation

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "Kubernetes security best practices RBAC",
      included_sources=[
          "kubernetes.io/docs",
          "docs.aws.amazon.com",
          "cloud.google.com/kubernetes-engine/docs"
      ]
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "Kubernetes security best practices RBAC",
    {
      includedSources: [
        'kubernetes.io/docs',
        'docs.aws.amazon.com',
        'cloud.google.com/kubernetes-engine/docs'
      ]
    }
  );
  ```
</CodeGroup>

### News

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "artificial intelligence regulation European Union",
      included_sources=[
          "scholar.google.com",
          "gov.uk/search/news",
          "who.int",
          "europa.eu",
          "politico.eu"
      ]
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "artificial intelligence regulation European Union",
    {
      includedSources: [
        'scholar.google.com',
        'gov.uk/search/news',
        'who.int',
        'europa.eu',
        'politico.eu'
      ]
    }
  );
  ```
</CodeGroup>

## Source Biases

Source biases let you influence ranking without hard filtering. Unlike `included_sources`/`excluded_sources`, biased sources can still appear (or be absent) based on relevance — biases just nudge the ranking.

Values range from **-5** (strong demotion) to **+5** (strong boost). A value of `0` has no effect.

### Boost Government Sources

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "climate change policy impact",
      source_biases={
          "epa.gov": 5,
          "nasa.gov": 4,
          "noaa.gov": 3,
          "nih.gov": 2,
          "example.com": -4
      }
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "climate change policy impact",
    {
      sourceBiases: {
        "epa.gov": 5,
        "nasa.gov": 4,
        "noaa.gov": 3,
        "nih.gov": 2,
        "example.com": -4
      }
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "climate change policy impact",
      "source_biases": {
        "epa.gov": 5,
        "nasa.gov": 4,
        "noaa.gov": 3,
        "nih.gov": 2,
        "example.com": -4
      }
    }'
  ```
</CodeGroup>

### Combine with Hard Filters

You can use `source_biases` alongside `included_sources` or `excluded_sources` for fine-grained control:

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "federal research funding allocation",
      excluded_sources=["example.com", "example.org"],
      source_biases={
          "nsf.gov": 5,
          "nih.gov": 4,
          "energy.gov": 3
      }
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "federal research funding allocation",
    {
      excludedSources: ["example.com", "example.org"],
      sourceBiases: {
        "nsf.gov": 5,
        "nih.gov": 4,
        "energy.gov": 3
      }
    }
  );
  ```
</CodeGroup>