--- title: "Get top news across companies" method: GET path: "/v1/top-news" tags: ["News"] --- # Get top news across companies `GET /v1/top-news` ## Request - Base URL: `https://api.fiscal.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.fiscal.ai/v1/top-news` - Auth: API key in query parameter `apiKey` 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. ## Query parameters - `apiKey` string: API Key (alternatively send via X-Api-Key header) - `companyKey` string: Optional. When provided, returns top news for this company only. Must be canonical EXCHANGE_TICKER form (e.g. NASDAQ_AAPL). - `startDate` string: 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. - `endDate` string: 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. - `eventType` string: 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. - `importance` integer: 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. - `minImportance` integer: 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. - `maxImportance` integer: 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). - `minMarketCap` number, 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. - `maxMarketCap` number, 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. - `directArticle` 'true' | 'false': Optional. We added directArticle because some customers prefer to tell these links apart. We recommend not filtering on it, so you get the full breadth of the news: a story is just as relevant whether its link opens the article itself or a list, feed or quote page. true returns only articles whose sourceUrl opens the story's own article; false returns only articles whose sourceUrl opens a list, feed or quote page. - `pageNumber` integer: Optional. Page number (1-indexed). Defaults to 1. - `pageSize` integer: Optional. Number of articles per page. Defaults to 250, max 1000. ## Response `200` Paginated top news articles sorted by importance (ascending) then collection timestamp (newest first). - object - `pagination` object, required - `page` number, required: Current page number (1-indexed). - `pageSize` number, required: Number of items per page. - `totalCount` number, required: Total number of deduped articles matching the filters. - `totalPages` number, required: Total number of pages. - `hasNextPage` boolean, required: Whether there is a next page. - `hasPreviousPage` boolean, required: Whether there is a previous page. - `data` object[], required - `companyKey` string, required: EXCHANGE_TICKER for the article's company. - `date` string, required: UTC date of the stored news file. - `title` string, required - `description` string, required - `summary` string, required - `eventType` string, required: News event category. - `importance` integer, required: Relative importance score. Scores run from 1 to 5: 1 = Major Event, 2 = Measurable Impact, 3 = Notable Update, 4 = Minor Mention, 5 = Routine Event. - `sourceUrl` string, required - `collectedAt` string, required: UTC timestamp when the article was collected. - `directArticle` boolean, required: true when sourceUrl opens the story's own article; false when it opens a list, feed or quote page. ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found ## Changes - **2026-10-17** `e96148e6bd76`: 2 info - added the new optional `query` request parameter `directArticle` - added the required property `data/items/directArticle` to the response with the `200` status [Operation history](https://skmtc.dev/fiscal/apis/fiscal-api/changes/v1/top-news/get.md) --- [API](https://skmtc.dev/fiscal/apis/fiscal-api.md) - [All operations](https://skmtc.dev/fiscal/apis/fiscal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fiscal/apis/fiscal-api/revisions/85026fdfc8b8?raw)