> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Breaking news

> Discover emerging stories with significant coverage traction using the breaking news endpoint.

Breaking news represents important stories rapidly gaining traction across
multiple sources. News API identifies these events by analyzing coverage
patterns and grouping articles by content similarity — surfacing high-impact
events as they emerge.

## How it works

<Steps>
  <Step title="Clustering">
    Recently published articles are automatically grouped based on content
    similarity.
  </Step>

  <Step title="Validation">
    Each cluster is analyzed for breaking news signals: sudden spikes in
    publication frequency, coverage across multiple publishers, and presence
    of high-ranking news sources.
  </Step>

  <Step title="Deduplication">
    Duplicate content within clusters is filtered out while preserving source
    diversity.
  </Step>

  <Step title="Historical analysis">
    New candidates are compared against recent breaking news to track continuing
    stories.
  </Step>

  <Step title="AI evaluation">
    An AI analysis step confirms whether a cluster represents a significant
    event.
  </Step>

  <Step title="Classification">
    Clusters meeting the breaking news criteria receive a special flag in the
    system.
  </Step>
</Steps>

When you query `/breaking_news`, you receive the most representative article
from each breaking news cluster. Results are ordered by cluster size, so the
most widely covered stories appear first.

## Query endpoint

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://v3-api.newscatcherapi.com/api/breaking_news" \
    -H "x-api-token: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "theme": "Business",
      "page_size": 100,
      "top_n_articles": 5
    }'
  ```

  ```python Python theme={null}
  from newscatcher import NewscatcherApi

  client = NewscatcherApi(api_key="YOUR_API_KEY")

  response = client.breaking_news.post(
      theme="Business",
      page_size=100,
      top_n_articles=5,
  )

  for event in response.breaking_news_events:
      print(f"Event {event.event_id}: {event.articles_count} articles")
      print(f"  Top article: {event.articles[0].title}")
  ```

  ```typescript TypeScript theme={null}
  import { NewscatcherApiClient } from "newscatcher-sdk";

  const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });

  const response = await client.breakingNews.post({
    theme: "Business",
    pageSize: 100,
    topNArticles: 5,
  });

  response.breakingNewsEvents?.forEach((event) => {
    console.log(`Event ${event.eventId}: ${event.articlesCount} articles`);
    console.log(`  Top article: ${event.articles?.[0]?.title}`);
  });
  ```

  ```java Java theme={null}
  import com.newscatcher.api.NewscatcherApiClient;
  import com.newscatcher.api.resources.breakingnews.requests.PostBreakingNewsRequest;

  NewscatcherApiClient client = NewscatcherApiClient.builder()
      .apiKey("YOUR_API_KEY")
      .build();

  var response = client.breakingNews().post(
      PostBreakingNewsRequest.builder()
          .theme("Business")
          .pageSize(100)
          .topNArticles(5)
          .build()
  );

  response.getBreakingNewsEvents().forEach(event -> {
      System.out.println("Event " + event.getEventId() + ": " + event.getArticlesCount() + " articles");
      System.out.println("  Top article: " + event.getArticles().get(0).getTitle());
  });
  ```
</CodeGroup>

## Response format

```json theme={null}
{
  "status": "ok",
  "total_hits": 465,
  "page": 1,
  "total_pages": 5,
  "page_size": 100,
  "breaking_news_events": [
    {
      "event_id": "15610469432059813057",
      "articles_count": 5842,
      "articles": [
        {
          "title": "...",
          "author": "...",
          "published_date": "...",
          "link": "...",
          "domain_url": "..."
        }
      ]
    }
  ]
}
```

For a full description of response fields, see the [Breaking news endpoint reference](/news-api/api-reference/breaking-news/retrieve-breaking-news-post).

## Comparison with other endpoints

|                 | Breaking news                                            | Search                                      | Latest headlines             |
| --------------- | -------------------------------------------------------- | ------------------------------------------- | ---------------------------- |
| Purpose         | Discover high-impact emerging stories                    | Find specific content                       | Retrieve recent headlines    |
| Time scope      | Fixed at 24 hours                                        | Configurable with `from_` and `to_`         | Configurable with `when`     |
| Result grouping | Clustered by event                                       | Individual articles                         | Individual articles          |
| Primary sorting | By cluster size                                          | By relevance, date, or rank                 | By publication date          |
| Use cases       | Media monitoring, market intelligence, crisis monitoring | Content curation, research, entity tracking | News feeds, topic monitoring |

## Use cases

* **Media monitoring** — quickly identify emerging stories without tracking multiple sources manually.
* **Content curation** — surface trending stories for newsletters, apps, or websites based on coverage traction.
* **Market intelligence** — detect potentially market-moving events as they gain media coverage.
* **Crisis monitoring** — identify sudden surges in coverage about topics of concern.

## See also

* [Breaking news endpoint reference](/news-api/api-reference/breaking-news/retrieve-breaking-news-post)
* [Clustering news articles](/news-api/guides-and-concepts/clustering-news-articles)