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

# Financial Data API for AI Agents - SEC Filings, Stock Data, Market Intelligence

> Access real-time financial data through one API. SEC 10-K/10-Q filings, stock prices, earnings reports, insider transactions, and market data for AI agents and RAG applications.

Search real-time market data, earnings reports, SEC filings, and regulatory updates. Valyu gives you structured financial data through a single API.

## What You Can Do

* **Investment research** - Access earnings, financial statements, and market trends
* **Risk assessment** - Monitor market conditions and regulatory changes
* **Portfolio management** - Track holdings and performance metrics
* **Compliance monitoring** - Stay updated on regulatory filings

## Features

<CardGroup cols={2}>
  <Card title="Real-Time Market Data" icon="chart-line">
    Current stock prices, crypto rates, forex data, and market movers.
  </Card>

  <Card title="Structured Financial Data" icon="table">
    Earnings data, balance sheets, income statements, and cash flows.
  </Card>

  <Card title="Regulatory Filings" icon="building-columns">
    SEC 10-K, 10-Q, 8-K, 13F holdings, 13D/13G ownership filings.
  </Card>

  <Card title="Market Intelligence" icon="magnifying-glass-chart">
    Institutional holdings, ownership changes, insider transactions, and dividend data.
  </Card>
</CardGroup>

## Available Datasets

### Market Data

| **Dataset**               | **Content**                   | **Use Case**                 |
| ------------------------- | ----------------------------- | ---------------------------- |
| `valyu/valyu-stocks`      | Real-time global stock prices | Live market monitoring       |
| `valyu/valyu-crypto`      | Cryptocurrency prices         | Crypto trading and analysis  |
| `valyu/valyu-forex`       | Foreign exchange rates        | Currency trading and hedging |
| `valyu/valyu-etfs`        | ETF prices and data           | ETF trading and analysis     |
| `valyu/valyu-funds`       | Mutual fund prices            | Fund research and tracking   |
| `valyu/valyu-commodities` | Commodity futures prices      | Commodity trading            |

### Fundamental Analysis

| **Dataset**                       | **Content**                      | **Use Case**              |
| --------------------------------- | -------------------------------- | ------------------------- |
| `valyu/valyu-earnings-US`         | Quarterly and annual earnings    | Performance analysis      |
| `valyu/valyu-statistics-US`       | Key financial metrics and ratios | Quick company metrics     |
| `valyu/valyu-balance-sheet-US`    | Balance sheet data               | Financial health analysis |
| `valyu/valyu-income-statement-US` | Revenue, expenses, profitability | Profitability assessment  |
| `valyu/valyu-cash-flow-US`        | Cash flow activities             | Liquidity analysis        |
| `valyu/valyu-dividends-US`        | Dividend information             | Income investing          |

### Market Intelligence

| **Dataset**                           | **Content**                          | **Use Case**         |
| ------------------------------------- | ------------------------------------ | -------------------- |
| `valyu/valyu-insider-transactions-US` | Executive and institutional trading  | Sentiment analysis   |
| `valyu/valyu-market-movers-US`        | Biggest gainers, losers, most active | Trend identification |

### Regulatory

| **Dataset**               | **Content**                                                   | **Use Case**                                      |
| ------------------------- | ------------------------------------------------------------- | ------------------------------------------------- |
| `valyu/valyu-sec-filings` | SEC filings: 10-K, 10-Q, 8-K, 13F holdings, 13D/13G ownership | Compliance, ownership tracking, and deep research |

### Economic Data

| **Dataset**                        | **Content**                                           | **Use Case**                   |
| ---------------------------------- | ----------------------------------------------------- | ------------------------------ |
| `valyu/valyu-destatis-labour`      | German labour market statistics                       | German economic research       |
| `valyu/valyu-fred`                 | Federal Reserve data (interest rates, GDP, inflation) | US economic analysis           |
| `valyu/valyu-bls`                  | Bureau of Labor Statistics data                       | US labour market and inflation |
| `valyu/valyu-worldbank-indicators` | World Bank development indicators                     | Global economic research       |
| `valyu/valyu-usaspending`          | US federal spending data                              | Government spending analysis   |

<Tip>
  Use structured datasets (earnings, balance sheets) for metrics. Use SEC filings
  for detailed context and qualitative analysis.
</Tip>

## Quick Start

### Basic Search

Let Valyu find the right datasets automatically:

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

  valyu = Valyu("your-api-key-here")

  response = valyu.search(
      "Apple's latest quarterly earnings and revenue growth trends"
  )

  print(response)

  ```

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

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

  const response = await valyu.search("Apple's latest quarterly earnings and revenue growth trends");

  console.log(response);
  ```

  ```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": "Apple latest quarterly earnings and revenue growth trends"
    }'
  ```
</CodeGroup>

### Real-Time Market Data

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "today's biggest stock gainers and notable insider trading activity"
  )

  # Crypto and forex
  crypto_response = valyu.search(
      "Bitcoin price trends this week and current EUR/USD exchange rate"
  )

  ```

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

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

  const response = await valyu.search("today's biggest stock gainers and notable insider trading activity");

  const cryptoResponse = await valyu.search("Bitcoin price trends this week and current EUR/USD exchange rate");
  ```

  ```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": "todays biggest stock gainers and notable insider trading activity"
    }'
  ```
</CodeGroup>

### Company Analysis

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "Tesla's latest income statement and cash flow analysis Q4 2024"
  )

  performance = valyu.search(
      "Microsoft stock price performance and recent quarterly results"
  )

  ```

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

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

  const response = await valyu.search("Tesla's latest income statement and cash flow analysis Q4 2024");

  const performance = await valyu.search("Microsoft stock price performance and recent quarterly results");
  ```

  ```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": "Tesla latest income statement and cash flow analysis Q4 2024"
    }'
  ```
</CodeGroup>

## Advanced Usage

### Target Specific Datasets

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

  valyu = Valyu("your-api-key-here")

  # Just earnings data
  earnings_only = valyu.search(
      "Tesla quarterly earnings",
      included_sources=["valyu/valyu-earnings-US"]
  )

  # Multiple financial datasets
  comprehensive = valyu.search(
      "Microsoft financial performance analysis",
      included_sources=[
          "valyu/valyu-income-statement-US",
          "valyu/valyu-balance-sheet-US",
          "valyu/valyu-cash-flow-US"
      ]
  )

  ```

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

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

  const earningsOnly = await valyu.search(
    "Tesla quarterly earnings",
    {
      includedSources: ['valyu/valyu-earnings-US']
    }
  );

  const comprehensive = await valyu.search(
    "Microsoft financial performance analysis",
    {
      includedSources: [
        'valyu/valyu-income-statement-US',
        'valyu/valyu-balance-sheet-US',
        'valyu/valyu-cash-flow-US'
      ]
    }
  );
  ```

  ```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": "Tesla quarterly earnings",
      "included_sources": ["valyu/valyu-earnings-US"]
    }'
  ```
</CodeGroup>

### SEC Filings, Holdings & Ownership

Search 3M+ SEC filings and structured data using natural language. No accession numbers, CIK codes, or technical syntax required - just describe what you need.

**What you can search:**

* **10-K annual reports** - Full financial statements, MD\&A, risk factors, business descriptions
* **10-Q quarterly reports** - Interim financials, quarterly updates, management commentary
* **8-K current reports** - Material events, M\&A announcements, leadership changes
* **13F-HR institutional holdings** - Quarterly portfolio disclosures from hedge funds and asset managers with \$100M+ AUM
* **SC 13D activist ownership** - Beneficial ownership filings from investors acquiring 5%+ with activist intent
* **SC 13G passive ownership** - Simplified beneficial ownership filings from passive 5%+ investors

**Key capabilities:**

* Ask for a **specific section** (e.g., "risk factors", "MD\&A", "business description")
* Use just the **company name** - no ticker symbol or accession number needed
* Retrieve **entire filings** by setting `response_length="max"` (up to 400k characters)
* Search by **time period** (e.g., "FY2024", "Q3 2023", "during 2020")
* Track **institutional holdings** changes across quarters via 13F filings
* Monitor **activist campaigns** and ownership stakes via 13D/13G filings

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

  valyu = Valyu("your-api-key-here")

  # Get a specific section from a filing
  risk_factors = valyu.search(
      "Apple 10-K risk factors section"
  )

  # Full annual report (use responseLength="max" for complete filing)
  full_filing = valyu.search(
      "Tesla 10-K FY2024",
      response_length="max"
  )

  # Search for topics across filings
  ai_strategy = valyu.search(
      "mentions of AI strategy in Microsoft's 2024 SEC filings"
  )

  # Insider transactions (Form 4 structured data)
  insider_trades = valyu.search(
      "insider transactions for Pfizer during 2020"
  )

  ```

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

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

  // Get a specific section from a filing
  const riskFactors = await valyu.search(
    "Apple 10-K risk factors section"
  );

  // Full annual report
  const fullFiling = await valyu.search(
    "Tesla 10-K FY2024",
    { responseLength: "max" }
  );

  // Search for topics across filings
  const aiStrategy = await valyu.search(
    "mentions of AI strategy in Microsoft's 2024 SEC filings"
  );

  // Insider transactions (Form 4 structured data)
  const insiderTrades = await valyu.search(
    "insider transactions for Pfizer during 2020"
  );
  ```

  ```bash cURL theme={null}
  # Get risk factors section
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Apple 10-K risk factors section"
    }'

  # Full filing with max response length
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Tesla 10-K FY2024",
      "response_length": "max"
    }'

  # Insider transactions
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "insider transactions for Pfizer during 2020"
    }'
  ```
</CodeGroup>

<Note>
  **Response length options:**

  * `short` - 25k characters (default)
  * `medium` - 50k characters
  * `large` - 100k characters
  * `max` - up to 400k characters (\~100k tokens)

  Use `max` only when you need complete filings and your context window supports it.
</Note>

### Institutional Holdings & Ownership (13F, 13D, 13G)

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

  valyu = Valyu("your-api-key-here")

  # 13F: Track Goldman Sachs institutional holdings
  institutional = valyu.search(
      "Goldman Sachs 13F-HR holdings report"
  )

  # 13D: Monitor activist ownership filings
  activist = valyu.search(
      "13D filings for Apple"
  )

  # 13G: Track passive ownership disclosures
  passive = valyu.search(
      "What stocks does BlackRock passively hold according to 13G filings?"
  )

  ```

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

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

  // 13F: Track Goldman Sachs institutional holdings
  const institutional = await valyu.search(
    "Goldman Sachs 13F-HR holdings report"
  );

  // 13D: Monitor activist ownership filings
  const activist = await valyu.search(
    "13D filings for Apple"
  );

  // 13G: Track passive ownership disclosures
  const passive = await valyu.search(
    "What stocks does BlackRock passively hold according to 13G filings?"
  );
  ```

  ```bash cURL theme={null}
  # 13F institutional holdings
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Goldman Sachs 13F-HR holdings report"
    }'

  # 13D activist ownership
  curl -X POST https://api.valyu.ai/v1/search \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "13D filings for Apple"
    }'
  ```
</CodeGroup>

<Tip>
  **13D vs 13G**: Both report 5%+ ownership stakes. **13D** = activist intent (influencing management), **13G** = passive investor. A 13D filing often signals potential activist campaigns — valuable for event-driven strategies.
</Tip>

### Financial News

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "Federal Reserve interest rate policy impact on banking sector",
      included_sources=[
          "treasury.gov",
          "sec.gov",
          "bls.gov",
          "federalreserve.gov"
      ]
  )

  ```

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

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

  const response = await valyu.search(
    "Federal Reserve interest rate policy impact on banking sector",
    {
      includedSources: [
        'treasury.gov',
        'sec.gov',
        'bls.gov',
        'federalreserve.gov'
      ]
    }
  );
  ```

  ```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": "Federal Reserve interest rate policy impact on banking sector",
      "included_sources": ["treasury.gov", "sec.gov", "bls.gov", "federalreserve.gov"]
    }'
  ```
</CodeGroup>

## Common Use Cases

* **Investment research**: Earnings, KPIs, valuation comps, guidance analysis
* **Market monitoring**: Real-time movers, news, crypto/forex, insider activity
* **Portfolio analytics**: Holdings performance, dividends, risk exposures
* **Regulatory compliance**: 10-K/10-Q/8-K filings, risk factors, SEC updates
* **Institutional holdings**: 13F portfolio tracking, fund position changes, concentration analysis
* **Ownership monitoring**: 13D activist campaigns, 13G passive ownership, beneficial ownership changes
* **Competitive intelligence**: Product mentions, partnerships, strategy in filings
* **Risk assessment**: Macro sensitivity, sector risks, policy impacts

## Examples

### Investment Research

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

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "NVIDIA financial performance GPU market share competitive position 2024",
      max_num_results=15
  )

  analyst_view = valyu.search(
      "NVIDIA stock analyst ratings price targets Q4 2024",
      included_sources=[
          "treasury.gov",
          "sec.gov",
          "fred.stlouisfed.org"
      ]
  )

  ```

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

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

  const response = await valyu.search(
    "NVIDIA financial performance GPU market share competitive position 2024",
    {
      maxNumResults: 15
    }
  );

  const analystView = await valyu.search(
    "NVIDIA stock analyst ratings price targets Q4 2024",
    {
      includedSources: [
        "treasury.gov",
        "sec.gov",
        "fred.stlouisfed.org"
      ]
    }
  );
  ```
</CodeGroup>

### Portfolio Management

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

  valyu = Valyu("your-api-key-here")

  portfolio_earnings = valyu.search(
      "Apple Microsoft Tesla quarterly earnings results 2024"
  )

  dividend_stocks = valyu.search(
      "high dividend yield stocks quarterly payments 2024",
      included_sources=["valyu/valyu-dividends-US"]
  )

  ```

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

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

  const portfolioEarnings = await valyu.search(
    "Apple Microsoft Tesla quarterly earnings results 2024"
  );

  const dividendStocks = await valyu.search(
    "high dividend yield stocks quarterly payments 2024",
    {
      includedSources: ['valyu/valyu-dividends-US']
    }
  );
  ```
</CodeGroup>

### Regulatory Compliance

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

  valyu = Valyu("your-api-key-here")

  reg_updates = valyu.search(
      "SEC cryptocurrency regulation banking industry impact 2024",
      included_sources=[
          "sec.gov",
          "federalreserve.gov",
          "sec.gov/cgi-bin/browse-edgar"
      ]
  )

  compliance = valyu.search(
      "new ESG reporting requirements public companies 2024"
  )

  ```

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

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

  const regUpdates = await valyu.search(
    "SEC cryptocurrency regulation banking industry impact 2024",
    {
      includedSources: [
        "sec.gov",
        "federalreserve.gov",
        "sec.gov/cgi-bin/browse-edgar"
      ]
    }
  );

  const compliance = await valyu.search(
    "new ESG reporting requirements public companies 2024"
  );
  ```
</CodeGroup>

### Market Intelligence

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

  valyu = Valyu("your-api-key-here")

  sector_analysis = valyu.search(
      "renewable energy sector growth rates market opportunities 2024"
  )

  insider_activity = valyu.search(
      "technology sector insider buying activity large transactions",
      included_sources=["valyu/valyu-insider-transactions-US"]
  )

  ```

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

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

  const sectorAnalysis = await valyu.search(
    "renewable energy sector growth rates market opportunities 2024"
  );

  const insiderActivity = await valyu.search(
    "technology sector insider buying activity large transactions",
    {
      includedSources: ['valyu/valyu-insider-transactions-US']
    }
  );
  ```
</CodeGroup>

## Choosing the Right Dataset

<Warning>
  Choose the right dataset for your needs. Structured datasets give you clean
  metrics; SEC filings provide detailed context.
</Warning>

### Structured Datasets

Use for:

* Quick financial ratios and metrics
* Earnings comparisons across quarters
* Balance sheet analysis
* Cash flow tracking
* Dividend history

```python theme={null}
response = valyu.search(
    "Apple P/E ratio debt-to-equity current ratio",
    included_sources=["valyu/valyu-statistics-US"]
)
```

### SEC Filings

Use for:

* Business strategy analysis
* Risk factor assessment
* Management discussion and analysis
* Competitive positioning
* Qualitative insights

```python theme={null}
response = valyu.search(
    "Tesla's business strategy and competitive advantages analysis"
)
```

## Best Practices

<Tip>
  Start with descriptive prompts and let Valyu find relevant datasets. Use
  `included_sources` only when you need specific data types.
</Tip>

### Effective Queries

| **Query Type**        | **Example**                                            | **Why It Works**                         |
| --------------------- | ------------------------------------------------------ | ---------------------------------------- |
| **Earnings**          | "Apple Q4 2024 earnings revenue growth year-over-year" | Specific company, timeframe, and metrics |
| **Market Trends**     | "Stock performance biggest gainers today"              | Clear focus with current data            |
| **Financial Health**  | "Tesla balance sheet debt levels cash position"        | Specific statement and metrics           |
| **Regulatory Impact** | "Federal Reserve rate hikes impact on banking stocks"  | Event context with sector focus          |

### Source Selection

**Market Analysis**:

```python theme={null}
included_sources = [
    "oecd.org",
    "sec.gov/cgi-bin/browse-edgar",
    "data.worldbank.org",
    "eurostat.ec.europa.eu"
]
```

**Company Fundamentals**:

```python theme={null}
included_sources = [
    "valyu/valyu-earnings-US",
    "valyu/valyu-statistics-US",
    "valyu/valyu-balance-sheet-US"
]
```

**Regulatory Research**:

```python theme={null}
included_sources = [
    "sec.gov",
    "federalreserve.gov",
    "treasury.gov"
]
```

### Tips

1. **Use financial terms** to trigger relevant datasets automatically
2. **Include company names** or tickers for targeted results
3. **Add time context** ("latest", "Q4 2024", "recent") for current data
4. **Specify metrics** like "earnings", "revenue", or "cash flow"

## Limitations

* **Data delays**: Market data may have 1-5 minute delays
* **Regional focus**: Some Structured datasets currently cover US markets
* **Access levels**: Some premium content may require subscriptions