news
Read-only
Search already-synthesized news events — pre-built story digests — or fetch one by id.
Each story comes with a generated headline, one-liner, abstract, key actors, and
industry/event-type labels. Use it for a quick digest of what happened, for
deal/incident-type or industry filtering, and for corroboration ranking. Nothing is
required: a bare call returns the most-corroborated stories of the last 24 hours.
Limits — keyless: 7-day from_ lookback, 20 calls/hour, 20 stories per call, over-limit
narrowed with a notice. With a key: per-plan ceilings (free tier today 14 days, 50
calls/hour, 50 stories), over-limit rejected rather than narrowed. Call check_limits
for the live numbers; it is free and never spends the budget it reports on.
Filters combine with AND; event_type, content_type, and sector each accept
several comma-separated values combined with OR.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Optional search terms, matched case-insensitively against the story's headline, one-liner, abstract, and named actors (no article body text, no stemming). Space-separated words are ANDed, so ALWAYS quote a multi-word phrase: `layoffs OR "workforce reduction"` works, `layoffs OR workforce reduction` is read as a mix of AND/OR and rejected. Supports AND/OR/NOT (aliases &&, ||, !), ( ) grouping, and `*` wildcards. NEAR() and MULTIPLE() are NOT supported here — they are silently read as ordinary words instead of erroring, so never use them. Omit q entirely for a filter-only digest ("banking news today" needs no q at all). | |
| sort | No | What "best" means for this call. **Omit it** unless the user asked for a specific ordering: the API then picks `relevance` when `q` or `subject` is set and `newsrooms` when neither is, which is almost always right. Forcing `newsrooms` on a keyword search ranks by story size rather than match, so `subject="Bank of America"` returns "India Now Asia's Least Preferred Stock Market" ahead of "Bank of America Warns of European Stock Decline" — big stories that merely mention the words. `newsrooms`: most independently-corroborated first. `trending`: corroboration weighted by freshness on an 8-hour half-life — the one for "what is blowing up right now". `relevance`: best semantic match to q first, and REQUIRES q. `last_seen`: most recently active. `first_seen`: most recently started. `size`: most articles. `source_count`: most publisher domains, mirrors included. `confidence`: highest label confidence, unlabeled last regardless of order. | |
| from_ | No | Inclusive lower bound on when the story BEGAN (its first_seen) — NOT the publish date of any one article, so a story still running today but started last week falls outside the default window. ISO 8601 (`2026-07-01T00:00:00`) or a relative phrase (`now-6h`, `2 days ago`, `yesterday`); all dates are UTC. Default: 24 hours ago, much narrower than a general news search — widening this is the FIRST thing to try when a query that should match something returns nothing — but the lookback is capped: 7 days keyless (narrowed with a notice), and per-plan with a key (14 days on the free tier today, rejected rather than narrowed). `check_limits` reports the caller's live ceiling. | |
| limit | No | Stories per page, 1–50, default 20, but capped for the caller: keyless 20 (softly, with a notice), and per-plan with a key (50 on the free tier today, over it is a validation error naming the maximum). `check_limits` reports the live cap. Raise it when the user asks for breadth — one call with a a flat ceiling rather than a page size: there is no paging past it, since the hourly call budget is the scarce resource (keyless 20/hour, 50/hour on the free tier). | |
| sector | No | Industry the story belongs to. Comma-separated for OR (`software_it_services,semiconductors` = "tech and chips"). One of: government_public_sector, media_entertainment, financial_services, healthcare_pharma, energy_utilities, retail_consumer, real_estate, agriculture_food, telecommunications, automotive, manufacturing_industrial, transport_logistics, aerospace_defense, mining_metals, construction_infrastructure, education, hospitality_travel, sports_recreation, nonprofit_ngo, legal_services, insurance, software_it_services, ecommerce, banking, defense_security, chemicals, fashion_apparel, gaming_esports, biotechnology, semiconductors, other_sector. | |
| subject | No | A single company, person, place, or organisation to centre the search on — plain name, no quoting. Quoted for you, which is the difference between a phrase and a bag of words: `Bank of America` unquoted ANDs three common terms and surfaces "Medtronic Revenue Grows" first, while the quoted phrase surfaces Bank of America. Combines with `q` (subject AND query), so `subject="Tesla", q="recall OR lawsuit"` reads as expected. Setting it also widens the default window from 24 hours to 30 days (clamped to the plan), because a company can go a fortnight without news — that is the single most common reason a name search comes back empty. Pass an explicit `from_` to override. | |
| event_id | No | Superseded by the `get_story` tool, which does this with two arguments instead of nineteen and can return every source link. Kept for compatibility. Fetch ONE story directly by the `event_id` of an earlier result (e.g. `evt_...`) — use it for "pull that story up again". When set, every other filter is ignored. Stories are occasionally folded into a more complete story as coverage develops: that returns 404 naming the replacement id, so fetch that id instead. An id that never existed returns a plain not-found. | |
| verbosity | No | Controls ONLY the source-link list; headline, summary, actors, and labels are always present. `compact`: no links. `standard` (default): up to 3. `full`: every link, uncapped — use it for "show me every source", but it makes a large `limit` very long. | standard |
| event_type | No | What KIND of event the story is, independent of industry. Exact `family.leaf` value; a bare family (`deals`) is invalid and unknown values are rejected naming them. Comma-separated for OR (`deals.merger_acquisition,funding.venture_funding_round` = "M&A or funding news"). The taxonomy is 59 leaves across 21 families, plus the standalone value `unclassifiable` for a labeled-but-uncategorizable story. Families: corporate_finance, markets, deals, governance, society_environment, sports, justice_crime, security, macro_policy, research_science, religion_society, politics, legal_regulatory, culture_media, product, accidents_disasters, operations, funding, local_civic, geopolitics, corporate_comms. The complete set of accepted values: corporate_finance.earnings_report, corporate_finance.analyst_rating, corporate_finance.dividends, markets.stock_move, markets.commodity_price, markets.currency_move, deals.merger_acquisition, deals.ipo_filing, deals.asset_sale, governance.board_change, governance.shareholder_vote, governance.executive_departure, society_environment.climate_event, society_environment.public_health, society_environment.environmental_incident, sports.match_result, sports.transfer_signing, sports.championship, justice_crime.arrest_charge, justice_crime.trial_verdict, justice_crime.investigation, security.cyberattack, security.data_breach, security.physical_security_incident, macro_policy.central_bank_decision, macro_policy.trade_policy, macro_policy.fiscal_policy, research_science.scientific_discovery, research_science.clinical_trial_result, research_science.publication, religion_society.religious_event, religion_society.social_movement, politics.election, politics.policy_announcement, politics.diplomacy, legal_regulatory.regulatory_action, legal_regulatory.lawsuit_filed, legal_regulatory.compliance_ruling, culture_media.celebrity_news, culture_media.entertainment_release, culture_media.award, product.product_launch, product.product_recall, product.feature_update, accidents_disasters.natural_disaster, accidents_disasters.industrial_accident, accidents_disasters.transport_accident, operations.plant_closure, operations.layoffs, operations.supply_chain_disruption, funding.venture_funding_round, funding.grant_award, local_civic.local_government_action, local_civic.infrastructure_project, geopolitics.armed_conflict, geopolitics.sanctions, geopolitics.diplomacy_summit, corporate_comms.press_release, corporate_comms.leadership_statement, unclassifiable. | |
| content_type | No | The FORM the reporting takes, independent of what it is about. Comma-separated for OR. One of: news_report, press_release, service_info, human_interest, explainer, commentary, analysis, opinion, interview, obituary. There is no NOT on this field, so for "analysis, not straight news" name the forms wanted (`analysis`) rather than the ones to exclude. | |
| min_newsrooms | No | Minimum outlets that reported INDEPENDENTLY, mirrors excluded — the strongest is-this-real signal. Reach for this over min_sources whenever the user wants to exclude a story that one outlet ran and everyone else reprinted. `3` ≈ "well-corroborated only". | |
| response_format | No | Output shape in content[0].text. Default `markdown` (readable digest). `text` = plain lines. `json` = full API payload. Match what the user asks for. | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| total | No | Total matching stories; present for a search call. | |
| events | No | Present for a search call (event_id unset). | |
| keyless_notices | No | Present when a keyless caller's request was narrowed. |