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

# Datasources

> Discover available data sources and categories with the Valyu Python SDK

A tool manifest for AI agents to discover available data sources at runtime, then pass their ids into Search, Answer, or DeepResearch via `included_sources`.

Agent note: Valyu's full docs index is at [/llms.txt](https://docs.valyu.ai/llms.txt) (full text at /llms-full.txt); append `.md` to any page URL for Markdown; hosted docs MCP at [https://docs.valyu.ai/mcp](https://docs.valyu.ai/mcp); integration reference at [/AGENTS.md](https://docs.valyu.ai/AGENTS.md).

<Prompt description="Discover Valyu **data sources** at runtime with the Python SDK." icon="database" actions={["copy","cursor"]}>
  You are using the Valyu Datasources API (a tool manifest) so an agent can discover available data sources at runtime, then pass their ids into Search/Answer/DeepResearch via `included_sources`.

  Setup:

  * Install: `pip install valyu`
  * Auth: set the `VALYU_API_KEY` environment variable (read automatically), or pass `Valyu(api_key="...")`. The SDK calls `https://api.valyu.ai/v1/datasources` with the `x-api-key` header.

  ```python theme={null}
  from valyu import Valyu

  valyu = Valyu()

  # All categories with dataset counts
  cats = valyu.datasources_categories()

  # Datasources in a category (e.g. "research", "markets", "company", "healthcare")
  ds = valyu.datasources(category="research")
  source_ids = [d.id for d in ds.datasources]

  # Feed discovered ids into a search
  valyu.search("transformer architecture improvements", included_sources=source_ids)
  ```

  Each `Datasource` exposes `id`, `name`, `category`, `pricing.cpm`, and `example_queries` (useful for few-shot prompting). Use it to map a query domain to the right sources before searching.

  Notes for the user: many listed sources are premium and require a subscription to query; a plan also lowers cost per credit. Surface this if they try to use sources their plan does not include.
</Prompt>

## Basic usage

```python theme={null}
from valyu import Valyu

valyu = Valyu()

# List datasources (optionally filtered by category)
response = valyu.datasources(category="research")
source_ids = [ds.id for ds in response.datasources]

# Feed them straight into a search
valyu.search("latest transformer architecture improvements", included_sources=source_ids)

# List categories with dataset counts
for cat in valyu.datasources_categories().categories:
    print(cat.id, cat.name, cat.dataset_count)
```

`example_queries` on each datasource doubles as few-shot examples for prompting, and `pricing.cpm` lets you estimate cost before searching.

### Categories

| Category         | Description                              |
| ---------------- | ---------------------------------------- |
| `research`       | Academic papers (arXiv, PubMed, bioRxiv) |
| `healthcare`     | Clinical trials, drug info, health data  |
| `markets`        | Stocks, crypto, forex, ETFs              |
| `company`        | SEC filings, earnings, insider trades    |
| `economic`       | FRED, BLS, World Bank data               |
| `predictions`    | Polymarket, Kalshi                       |
| `transportation` | UK Rail, ship tracking                   |
| `legal`          | Case law, legislation                    |
| `politics`       | Parliamentary data                       |
| `patents`        | Global patent filings                    |

<Tip>
  For more on filtering by sources, see the [Source Filtering Guide](/search/filtering/sources).
</Tip>

## Reference

<AccordionGroup>
  <Accordion title="Methods">
    | Method                       | Description                                       |
    | ---------------------------- | ------------------------------------------------- |
    | `datasources(category=None)` | List datasources, optionally filtered by category |
    | `datasources_categories()`   | List all categories with dataset counts           |
  </Accordion>

  <Accordion title="Response format">
    ```python theme={null}
    class DatasourcesResponse:
        success: bool
        error: Optional[str]
        datasources: List[Datasource]

    class Datasource:
        id: str                              # e.g., "valyu/valyu-arxiv"
        name: str
        description: str
        category: str
        type: Optional[str]
        modality: Optional[List[str]]
        topics: Optional[List[str]]
        languages: Optional[List[str]]
        source: Optional[str]
        example_queries: Optional[List[str]] # Sample queries for few-shot prompting
        pricing: Optional[DatasourcePricing] # .cpm = cost per million tokens
        response_schema: Optional[dict]
        update_frequency: Optional[str]
        size: Optional[int]
        coverage: Optional[DatasourceCoverage]  # .start_date / .end_date

    class DatasourceCategoriesResponse:
        success: bool
        error: Optional[str]
        categories: List[DatasourceCategory]

    class DatasourceCategory:
        id: str
        name: str
        description: Optional[str]
        dataset_count: int
    ```
  </Accordion>
</AccordionGroup>