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

# News Search API for AI - Real-Time News & Media Monitoring

> Search real-time news with date and country filtering. Build AI agents with access to current events, breaking news, and journalism content through one API.

Search real-time news articles with date and country filtering. News mode is optimised for finding current events, breaking news, and journalism content.

## What You Can Do

* **Media monitoring** - Track news coverage across topics and brands
* **Current events** - Get up-to-the-minute news on any subject
* **Journalism research** - Find sources and verify facts
* **PR and brand tracking** - Monitor mentions and sentiment
* **Trend analysis** - Identify emerging stories and patterns

## Features

<CardGroup cols={2}>
  <Card title="Real-Time News" icon="newspaper">
    Access current news articles from sources worldwide.
  </Card>

  <Card title="Date Filtering" icon="calendar-days">
    Filter by publication date for time-sensitive research.
  </Card>

  <Card title="Country Targeting" icon="globe">
    Focus on specific regions with country code filtering.
  </Card>

  <Card title="100 Results" icon="list-ol">
    Retrieve up to 100 results per query for comprehensive coverage.
  </Card>
</CardGroup>

## Quick Start

### Basic News Search

Search for news articles on any topic:

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

  valyu = Valyu()  # Uses VALYU_API_KEY from env

  response = valyu.search(
      query="artificial intelligence regulation updates",
      search_type="news",
      max_num_results=20,
  )

  for result in response["results"]:
      print(f"Title: {result['title']}")
      print(f"Date: {result.get('publication_date', 'N/A')}")
      print(f"URL: {result['url']}")
      print("---")
  ```

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

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

  const response = await valyu.search({
    query: "artificial intelligence regulation updates",
    searchType: "news",
    maxNumResults: 20,
  });

  response.results.forEach(result => {
    console.log(`Title: ${result.title}`);
    console.log(`Date: ${result.publicationDate || "N/A"}`);
    console.log(`URL: ${result.url}`);
    console.log("---");
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "artificial intelligence regulation updates",
      "search_type": "news",
      "max_num_results": 20
    }'
  ```
</CodeGroup>

### Date-Filtered Search

Filter news by publication date range:

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

  valyu = Valyu()

  response = valyu.search(
      query="climate change policy announcements",
      search_type="news",
      max_num_results=50,
      start_date="2025-01-01",
      end_date="2025-12-31",
  )

  print(f"Found {len(response['results'])} articles from 2025")

  for result in response["results"][:5]:
      print(f"{result.get('publication_date', 'N/A')}: {result['title']}")
  ```

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

  const valyu = new Valyu();

  const response = await valyu.search({
    query: "climate change policy announcements",
    searchType: "news",
    maxNumResults: 50,
    startDate: "2025-01-01",
    endDate: "2025-12-31",
  });

  console.log(`Found ${response.results.length} articles from 2025`);

  response.results.slice(0, 5).forEach(result => {
    console.log(`${result.publicationDate || "N/A"}: ${result.title}`);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "climate change policy announcements",
      "search_type": "news",
      "max_num_results": 50,
      "start_date": "2025-01-01",
      "end_date": "2025-12-31"
    }'
  ```
</CodeGroup>

### Country-Specific Search

Focus on news from specific regions:

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

  valyu = Valyu()

  # US news
  us_news = valyu.search(
      query="technology startup funding rounds",
      search_type="news",
      max_num_results=30,
      country_code="US",
  )

  # UK news
  uk_news = valyu.search(
      query="technology startup funding rounds",
      search_type="news",
      max_num_results=30,
      country_code="GB",
  )

  print(f"US articles: {len(us_news['results'])}")
  print(f"UK articles: {len(uk_news['results'])}")
  ```

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

  const valyu = new Valyu();

  // US news
  const usNews = await valyu.search({
    query: "technology startup funding rounds",
    searchType: "news",
    maxNumResults: 30,
    countryCode: "US",
  });

  // UK news
  const ukNews = await valyu.search({
    query: "technology startup funding rounds",
    searchType: "news",
    maxNumResults: 30,
    countryCode: "GB",
  });

  console.log(`US articles: ${usNews.results.length}`);
  console.log(`UK articles: ${ukNews.results.length}`);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "technology startup funding rounds",
      "search_type": "news",
      "max_num_results": 30,
      "country_code": "US"
    }'
  ```
</CodeGroup>

<Tip>
  Use ISO 3166-1 alpha-2 country codes: `US` (United States), `GB` (United Kingdom), `DE` (Germany), `FR` (France), etc.
</Tip>

## 100 Results

News mode supports up to 100 results per query. This requires the `increased_max_results` permission on your API key.

**To enable 100 results:**

1. Go to [API Key Management](http://platform.valyu.ai/user/account/apikeys?req=increase_results)
2. Request the `increased_max_results` permission
3. Create a new API key after approval

<Note>
  Without this permission, the default maximum is 20 results per query.
</Note>

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

  valyu = Valyu()  # Use API key with increased_max_results permission

  response = valyu.search(
      query="electric vehicle market news",
      search_type="news",
      max_num_results=100,  # Requires increased_max_results permission
      start_date="2025-01-01",
      country_code="US",
  )

  print(f"Retrieved {len(response['results'])} news articles")

  # Process all 100 results
  for i, article in enumerate(response["results"], 1):
      print(f"{i}. {article['title']}")
  ```

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

  const valyu = new Valyu(); // Use API key with increased_max_results permission

  const response = await valyu.search({
    query: "electric vehicle market news",
    searchType: "news",
    maxNumResults: 100, // Requires increased_max_results permission
    startDate: "2025-01-01",
    countryCode: "US",
  });

  console.log(`Retrieved ${response.results.length} news articles`);

  // Process all 100 results
  response.results.forEach((article, i) => {
    console.log(`${i + 1}. ${article.title}`);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "electric vehicle market news",
      "search_type": "news",
      "max_num_results": 100,
      "start_date": "2025-01-01",
      "country_code": "US"
    }'
  ```
</CodeGroup>

## Use Case Examples

### Multi-Topic News Monitoring

Track multiple topics in a single monitoring workflow:

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

  valyu = Valyu()

  def monitor_topics(topics: list, days_back: int = 7):
      """Monitor multiple news topics with date filtering."""
      end_date = datetime.now().strftime("%Y-%m-%d")
      start_date = (datetime.now() - timedelta(days=days_back)).strftime("%Y-%m-%d")
      
      results = {}
      
      for topic in topics:
          response = valyu.search(
              query=topic,
              search_type="news",
              max_num_results=20,
              start_date=start_date,
              end_date=end_date,
          )
          
          if response.get("success"):
              results[topic] = {
                  "count": len(response["results"]),
                  "articles": response["results"]
              }
              print(f"📰 {topic}: {len(response['results'])} articles")
      
      return results

  # Monitor tech and business topics
  news = monitor_topics([
      "artificial intelligence breakthroughs",
      "cryptocurrency regulation",
      "renewable energy investments",
      "tech layoffs announcements"
  ])
  ```

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

  const valyu = new Valyu();

  interface MonitoringResult {
    count: number;
    articles: any[];
  }

  async function monitorTopics(
    topics: string[],
    daysBack: number = 7
  ): Promise<Record<string, MonitoringResult>> {
    const endDate = new Date().toISOString().split("T")[0];
    const startDate = new Date(Date.now() - daysBack * 24 * 60 * 60 * 1000)
      .toISOString()
      .split("T")[0];

    const results: Record<string, MonitoringResult> = {};

    for (const topic of topics) {
      const response = await valyu.search({
        query: topic,
        searchType: "news",
        maxNumResults: 20,
        startDate,
        endDate,
      });

      if (response.success) {
        results[topic] = {
          count: response.results.length,
          articles: response.results
        };
        console.log(`📰 ${topic}: ${response.results.length} articles`);
      }
    }

    return results;
  }

  // Monitor tech and business topics
  const news = await monitorTopics([
    "artificial intelligence breakthroughs",
    "cryptocurrency regulation",
    "renewable energy investments",
    "tech layoffs announcements"
  ]);
  ```
</CodeGroup>

### Brand Monitoring

Track news mentions for brands or companies:

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

  valyu = Valyu()

  def brand_monitoring(brand: str, competitor_brands: list = None):
      """Monitor news for a brand and its competitors."""
      
      # Main brand news
      brand_news = valyu.search(
          query=f"{brand} news announcements",
          search_type="news",
          max_num_results=50,
      )
      
      print(f"=== {brand} News ===")
      print(f"Found {len(brand_news['results'])} articles")
      
      for article in brand_news["results"][:5]:
          print(f"  - {article['title']}")
      
      # Competitor comparison
      if competitor_brands:
          print(f"\n=== Competitor Coverage ===")
          for competitor in competitor_brands:
              comp_news = valyu.search(
                  query=f"{competitor} news",
                  search_type="news",
                  max_num_results=20,
              )
              print(f"{competitor}: {len(comp_news['results'])} articles")
      
      return brand_news

  # Monitor Tesla and competitors
  tesla_news = brand_monitoring(
      brand="Tesla",
      competitor_brands=["Rivian", "Lucid Motors", "Ford EV"]
  )
  ```

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

  const valyu = new Valyu();

  async function brandMonitoring(
    brand: string,
    competitorBrands: string[] = []
  ) {
    // Main brand news
    const brandNews = await valyu.search({
      query: `${brand} news announcements`,
      searchType: "news",
      maxNumResults: 50,
    });

    console.log(`=== ${brand} News ===`);
    console.log(`Found ${brandNews.results.length} articles`);

    brandNews.results.slice(0, 5).forEach(article => {
      console.log(`  - ${article.title}`);
    });

    // Competitor comparison
    if (competitorBrands.length > 0) {
      console.log(`\n=== Competitor Coverage ===`);
      for (const competitor of competitorBrands) {
        const compNews = await valyu.search({
          query: `${competitor} news`,
          searchType: "news",
          maxNumResults: 20,
        });
        console.log(`${competitor}: ${compNews.results.length} articles`);
      }
    }

    return brandNews;
  }

  // Monitor Tesla and competitors
  const teslaNews = await brandMonitoring(
    "Tesla",
    ["Rivian", "Lucid Motors", "Ford EV"]
  );
  ```
</CodeGroup>

### Breaking News Tracker

Monitor for breaking news on specific topics:

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

  valyu = Valyu()

  def breaking_news(topics: list, hours_back: int = 24):
      """Get recent breaking news on topics."""
      
      # Use today's date for recent news
      today = datetime.now().strftime("%Y-%m-%d")
      
      print(f"=== Breaking News ({today}) ===\n")
      
      for topic in topics:
          response = valyu.search(
              query=f"{topic} breaking news today",
              search_type="news",
              max_num_results=10,
              start_date=today,
              end_date=today,
          )
          
          if response.get("success") and response["results"]:
              print(f"🔴 {topic.upper()}")
              for article in response["results"][:3]:
                  print(f"   • {article['title']}")
                  print(f"     {article['url']}")
              print()

  # Track breaking news
  breaking_news([
      "stock market",
      "federal reserve",
      "technology",
      "politics"
  ])
  ```

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

  const valyu = new Valyu();

  async function breakingNews(topics: string[], hoursBack: number = 24) {
    const today = new Date().toISOString().split("T")[0];

    console.log(`=== Breaking News (${today}) ===\n`);

    for (const topic of topics) {
      const response = await valyu.search({
        query: `${topic} breaking news today`,
        searchType: "news",
        maxNumResults: 10,
        startDate: today,
        endDate: today,
      });

      if (response.success && response.results.length > 0) {
        console.log(`🔴 ${topic.toUpperCase()}`);
        response.results.slice(0, 3).forEach(article => {
          console.log(`   • ${article.title}`);
          console.log(`     ${article.url}`);
        });
        console.log();
      }
    }
  }

  // Track breaking news
  await breakingNews([
    "stock market",
    "federal reserve",
    "technology",
    "politics"
  ]);
  ```
</CodeGroup>

## Best Practices

1. **Use date filtering** - Always set `start_date` and `end_date` for time-sensitive queries
2. **Target regions** - Use `country_code` to focus on specific markets
3. **Request 100 results** - For comprehensive coverage, get the `increased_max_results` permission
4. **Combine with web search** - Use `search_type="all"` when you need both news and web content
5. **Monitor regularly** - Set up automated monitoring for ongoing topics

<Tip>
  For AI agent workflows, set `is_tool_call=true` to optimise results for LLM consumption.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Search Quickstart" icon="rocket" href="/search/quickstart">
    Learn the basics of the Search API
  </Card>

  <Card title="Date Filtering" icon="calendar-days" href="/search/filtering/date">
    Advanced date filtering options
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python-sdk/search">
    Full Python SDK documentation
  </Card>

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