v3

latestOpenAPI 3.1.02026-07-26490368.4 KB

News

Get top news across companies

Returns a paginated top-news feed across all covered companies.

Default behavior

When no filters are supplied, the endpoint returns articles from the latest 7 UTC days with importance 1 (Major Event) or 2 (Measurable Impact), restricted to companies with a market cap of at least $1B USD. Results are sorted by importance first, then newest collection timestamp. pageSize defaults to 250. The default view is optimized for high-signal monitoring, not as a complete relevance cutoff; include importance 3 or a wider range when you need a broader news view.

Filtering

Use importance for one exact level, or minImportance and maxImportance for an inclusive range. These modes are mutually exclusive. The scale runs from 1 (most material) to 5 (least material): use minImportance=1&maxImportance=3 to include Notable Update articles, or minImportance=1&maxImportance=5 to include every level.

eventType accepts one event type or a comma-separated list, for example eventType=earnings,ma.

Use minMarketCap and/or maxMarketCap (absolute USD) to filter by company market cap. The cross-company feed defaults to a $1B USD floor (minMarketCap=1000000000); pass minMarketCap=0 to disable it. These size filters apply to the cross-company feed only — supplying companyKey returns that company's news directly and ignores minMarketCap/maxMarketCap.

get/v1/top-news

Query parameters

apiKeystring

API Key (alternatively send via X-Api-Key header)

companyKeystring

Optional. When provided, returns top news for this company only. Must be canonical EXCHANGE_TICKER form (e.g. NASDAQ_AAPL).

Example:NASDAQ_AAPL

startDatestring

Optional start date of the inclusive UTC date range (YYYY-MM-DD). If supplied, endDate must also be supplied. If both are omitted, returns the latest 7 UTC days.

Example:2026-05-05

endDatestring

Optional end date of the inclusive UTC date range (YYYY-MM-DD). If supplied, startDate must also be supplied. Range cannot exceed 7 days. If both are omitted, returns the latest 7 UTC days.

Example:2026-05-11

eventTypestring

Optional. One or more event types, comma-separated. Defaults to all event types. Allowed: earnings, guidance, dividend, stock_split, buyback, ma, partnership, product_launch, expansion, regulatory, legal, executive, restructuring, financing, technology, esg, analyst, market_commentary, other.

Example:earnings,ma

importanceinteger

Optional. Exact importance level (1-5) to return. Mutually exclusive with minImportance/maxImportance. Scale: 1=Major Event, 2=Measurable Impact, 3=Notable Update, 4=Minor Mention, 5=Routine Event.

Example:2

minImportanceinteger

Optional. Inclusive lower bound on the importance value (1-5). Defaults to 1. Mutually exclusive with importance. Note the scale: 1 is the MOST significant tier; larger numbers are less significant.

Example:1

maxImportanceinteger

Optional. Inclusive upper bound on the importance value (1-5). Defaults to 5. Mutually exclusive with importance. Example: minImportance=1&maxImportance=2 returns the two most significant tiers (Major Event + Measurable Impact).

Example:3

minMarketCapnumber nullable

Optional. Inclusive lower bound on company USD market cap (absolute units, e.g. 1000000000 = $1B). Applies to the cross-company feed only (ignored when companyKey is supplied). Defaults to 1000000000 ($1B); pass minMarketCap=0 to disable the floor.

Example:1000000000

maxMarketCapnumber nullable

Optional. Inclusive upper bound on company USD market cap (absolute units). Applies to the cross-company feed only (ignored when companyKey is supplied). Defaults to no upper bound.

Example:50000000000

pageNumberinteger

Optional. Page number (1-indexed). Defaults to 1.

Example:1

pageSizeinteger

Optional. Number of articles per page. Defaults to 250, max 1000.

Example:250

Response

Paginated top news articles sorted by importance (ascending) then collection timestamp (newest first).

Example response

{
  "pagination": {
    "page": 1,
    "pageSize": 250,
    "totalCount": 2150,
    "totalPages": 9,
    "hasNextPage": true
  },
  "data": [
    {
      "companyKey": "NASDAQ_AAPL",
      "date": "2026-04-29",
      "title": "Company announces strategic acquisition",
      "description": "A short description of the material news event.",
      "summary": "A concise summary of the news and why it matters for the company.",
      "eventType": "ma",
      "importance": 2,
      "sourceUrl": "https://example.com/news/company-announces-acquisition",
      "collectedAt": "2026-04-29T01:47:11Z"
    }
  ]
}