Search News

Search news articles by keyword. Results are relevance-ranked.

GET /v1/news/search

Keywords only

Supply the topic you care about (e.g. apple earnings, climate summit). Plain keywords work best; boolean operators are not supported.

Query parameters

Parameter	Type	Default	Description
query	string	—	Required. Keyword(s), e.g. apple earnings or climate summit.
time_filter	string	(empty)	Recency window: day, week, month, or year. Empty for no restriction.
max_pages	integer	1	Number of pages to fetch. Each page returns up to ~20 articles. Maximum 50.

Pages are deduplicated across the result set, and fewer pages come back if there are no further results.

Examples

Basic keyword search:

curl -G "$LISTENX_BASE/v1/news/search" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'query=apple earnings'

Last 24 hours, three pages for a broader pull:

curl -G "$LISTENX_BASE/v1/news/search" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'query=climate summit' \
  --data-urlencode 'time_filter=day' \
  --data-urlencode 'max_pages=3'

Response

{
  "query": "apple earnings",
  "time_filter": "day",
  "pages_requested": 1,
  "pages_fetched": 1,
  "returned": 12,
  "results": [
    {
      "title": "Apple Launches Creative Labs Program With The King's Trust",
      "url": "https://www.macrumors.com/2026/10/07/apple-creative-labs-kings-trust/",
      "snippet": "Apple partners with The King's Trust to provide creative career education for young people.",
      "source": "www.macrumors.com",
      "published_at": "2026-10-08",
      "thumbnail_url": null
    }
  ],
  "billing": {
    "endpoint": "news.search",
    "units": 1,
    "unit_price": "0.010000",
    "amount": "0.010000",
    "balance_after": "97.240000",
    "request_id": "…"
  }
}

Fields

Field	Description
time_filter	The recency window applied (any, day, week, month, or year).
pages_requested	The max_pages you asked for.
pages_fetched	Pages actually fetched (also the number of billed units).
returned	Number of articles in results (deduplicated across pages).
results[]	Article summaries, in relevance order.

Result

Field	Description
title	Article headline.
url	Link to the article on the publisher's site.
snippet	Short text excerpt of the article.
source	Publisher domain, e.g. www.macrumors.com.
published_at	Publish date (ISO-8601), when available.
thumbnail_url	Preview image, when available.

Billing

Search is billed per page fetched — units = pages_fetched, minimum 1. So max_pages=3 costs up to 3 units (fewer if there are no more results). See Billing.

Notes

• News discovery is a public-web surface; results are not exhaustive and can shift over time.
• Each url points at the publisher's own article page, ready to open or ingest directly.