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

# News

> Find recent news articles about anything, newest first, each with its outlet and publish time.

`POST /v1/web/news` finds news articles about a query and returns them newest first. Every article comes with the outlet that published it and when it was published, and each link points at the publisher's own page. Turn on `scrapeResults` and each article also comes back read as clean data.

## When to use it

* You track announcements: funding rounds, acquisitions, launches, leadership changes, layoffs.
* You want what happened this week about a company or a topic, not the pages that rank best for it.
* You feed an agent that needs dated sources it can cite.

For general web pages, use [Search](https://docs.hydrafetch.com/endpoints/search.md). News answers "what was reported, and when"; search answers "which pages are about this".

## Example request

```bash cURL theme={null}
curl -X POST https://api.hydrafetch.com/v1/web/news \
  -H "X-API-Key: hf_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "startup raises series A",
    "timeRange": "week",
    "limit": 10
  }'
```

```javascript Node theme={null}
const res = await fetch("https://api.hydrafetch.com/v1/web/news", {
  method: "POST",
  headers: {
    "X-API-Key": "hf_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "startup raises series A",
    timeRange: "week",
    limit: 10,
  }),
});
const { data } = await res.json();
for (const a of data.results) {
  console.log(a.publishedAt, a.source, a.title, a.url);
}
```

```python Python theme={null}
import requests

res = requests.post(
    "https://api.hydrafetch.com/v1/web/news",
    headers={"X-API-Key": "hf_your_key_here"},
    json={"query": "startup raises series A", "timeRange": "week", "limit": 10},
)
for a in res.json()["data"]["results"]:
    print(a["publishedAt"], a["source"], a["title"], a["url"])
```

## Example response

```json theme={null}
{
  "data": {
    "query": "startup raises series A",
    "status": "ok",
    "results": [
      {
        "title": "Acme raises $45M in Series A round",
        "url": "https://example.com/news/acme-series-a",
        "source": "Example News",
        "publishedAt": "2026-11-03T09:12:00.000Z",
        "snippet": "The startup raised $45 million to expand into Europe.",
        "imageUrl": "https://example.com/images/acme.jpg",
        "data": null
      }
    ]
  }
}
```

## Writing a good query

* **For one company, search its name on its own.** News sources match the words you send. "Acme raises funding round" brings back general funding stories from English outlets, and they can push the company's own coverage out. "Acme" alone returns the articles that name it, and you can pick the funding ones from their titles.
* **Write the name the way its own press does.** A Chinese or Korean company is covered under its Chinese or Korean name. If you want one kind of event, add the word for it in that language, such as 融资 or 투자, not the English word.
* **Use `timeRange` for recency.** Do not put a month or a year into the query.
* **For a topic across companies, describe the event,** such as `startup raises series A` or `appoints chief executive`.

## Key options

**query** `string` *required*

What to find news about, like `acme raises funding` or `appoints chief executive`. Up to 500 characters.

**timeRange** `string` (default: week)

Only articles published within this window before now: `hour`, `day`, `week` or `month`.

**limit** `number` (default: 10)

How many articles to return, from 1 to 50. Newest first.

**country** `string`

ISO 3166 alpha-2 country code (for example `us`, `gb`, `in`) to lean results toward that country's coverage.

**includeDomains** `string[]`

Only return articles from these sites, like `techcrunch.com`. Up to 15.

**excludeDomains** `string[]`

Drop articles from these sites. Up to 15.

**maxAge** `number`

The oldest earlier answer to the same search you will accept, in milliseconds. By default we reuse an answer up to 5 minutes old for `hour`, 15 for `day` and 30 for `week` or `month`. Set `0` to always search fresh.

**scrapeResults** `boolean` (default: false)

When `true`, each article also comes back with its page read and returned as clean data, at **1 extra credit per article read**.

**scrapeOptions** `object`

How to read each article, using the same options as [Scrape](https://docs.hydrafetch.com/endpoints/scrape.md). Ignored when `scrapeResults` is `false`.

## Response fields

**data.status** `string`

`ok` when articles were found, `no_results` when none matched in the window. If news cannot be searched at all, the request fails with a 503 rather than returning an empty list.

**data.results** `object[]`

Articles, newest first. Each has `title`, `url` (the publisher's own page), `source` (the outlet), `publishedAt`, `snippet`, `imageUrl`, and `data`: the article read as clean data when `scrapeResults` is on, otherwise `null`.

`publishedAt` is exact when the listing gives a time. Some listings only say how long ago an article appeared, such as "2 days ago", and then `publishedAt` is worked out from that, so it can be off by up to that unit. An article listed more than once comes back once; when several outlets cover the same story, each outlet's article is its own result.

## Billing

A news search costs **1 credit**, and a search that finds nothing is free. With `scrapeResults` on, each article actually read costs **1 more**, the same as scraping that page directly.

## Related

> [card] [Search](https://docs.hydrafetch.com/endpoints/search.md)
>
> Search the whole web rather than the news.

> [card] [Jobs](https://docs.hydrafetch.com/endpoints/jobs.md)
>
> See who is hiring, alongside what they announced.

> [card] [Credits](https://docs.hydrafetch.com/concepts/credits.md)
>
> How every call is priced.

> [card] [API Reference](https://docs.hydrafetch.com/api-reference)
>
> Full `POST /v1/web/news` schema and a live playground.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.