> ## 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 TypeScript SDK

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

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 TypeScript 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 `includedSources`.

  Setup:

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

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

  const valyu = new Valyu();

  // All categories with dataset counts
  const cats = await valyu.datasources.categories();

  // Datasources in a category (e.g. "research", "markets", "company", "healthcare")
  const ds = await valyu.datasources.list({ category: "research" });
  const sourceIds = (ds.datasources ?? []).map((d) => d.id);

  // Feed discovered ids into a search
  await valyu.search("transformer architecture improvements", { includedSources: sourceIds });
  ```

  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

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

const valyu = new Valyu();

// List datasources (optionally filtered by category)
const response = await valyu.datasources.list({ category: "research" });
const sourceIds = (response.datasources ?? []).map((ds) => ds.id);

// Feed them straight into a search
await valyu.search("latest transformer architecture improvements", { includedSources: sourceIds });

// List categories with dataset counts
const { categories } = await valyu.datasources.categories();
categories?.forEach((cat) => console.log(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.list({ category? })` | List datasources, optionally filtered by category |
    | `datasources.categories()`        | List all categories with dataset counts           |
  </Accordion>

  <Accordion title="Response format">
    ```typescript theme={null}
    interface DatasourcesListResponse {
      success: boolean;
      error?: string;
      datasources?: Datasource[];
    }

    interface Datasource {
      id: string;                              // e.g., "valyu/valyu-arxiv"
      name: string;
      description: string;
      category: DatasourceCategoryId;
      type: string;
      modality: DatasourceModality[];
      topics: string[];
      languages?: string[];
      source?: string;
      example_queries: string[];               // Sample queries for few-shot prompting
      pricing: DatasourcePricing;              // .cpm = cost per million tokens
      response_schema?: Record<string, any>;
      update_frequency?: string;
      size?: number;
      coverage?: DatasourceCoverage;           // .start_date / .end_date
    }

    type DatasourceCategoryId =
      | "research" | "healthcare" | "patents" | "markets" | "company"
      | "economic" | "predictions" | "transportation" | "legal" | "politics";

    type DatasourceModality = "text" | "images" | "tabular";

    interface DatasourcesCategoriesResponse {
      success: boolean;
      error?: string;
      categories?: DatasourceCategory[];
    }

    interface DatasourceCategory {
      id: string;
      name: string;
      description: string;
      dataset_count: number;
    }
    ```
  </Accordion>
</AccordionGroup>