Sign in
news

Full-text search over the feed

Search the enriched feed by words. q is matched against each article's title, its summary and the entity names the enrichment extracted; the page comes back ranked (best match first, newest first among equal matches), with a per-item search_match and a query block that says how the words were read. symbol, category, source_type, item, min_relevance, from_date, to_date and collapse apply as hard filters on top, exactly as on /api/news/: q=director&item=5.02 searches 8-K filings that carry item 5.02, q="going concern"&source_type=gdelt searches press coverage only.

Query syntax. Bare words are all required (chip tariffs); a quoted phrase must appear in order ("going concern"); -word excludes (apple -iphone); OR separates alternatives (nvidia OR amd). Words in a non-Latin script are ignored. Matching tolerates one typo from five letters (prices reaches price) and a prefix on the last word; there is no stemming.

Modes (query.mode). strict: every word matched. broadened: the strict pass found fewer than 5 rows and the query has three or more words, so the most frequent words were dropped and the page carries rows with at least two of the query's words — search_match.terms_matched says how many on each; read these as leads, not matches. no_match: nothing in the searched window. no_terms: the query held no searchable words. Absence is not proof the event did not happen: the searched window starts at query.window_from.

Window and paging. The searched window is your plan's archive horizon (Free 30 days, Basic 90, Pro 180) unless from_date / to_date narrow it; a window reaching past the horizon returns 403 like the feed. Results are bounded to the best 200 matches (matched counts them, capped at 200) and paged with an opaque cursor that is bound to the query that issued it. Responses are private and never shared-cached.

Failure. When the search service does not answer in time the endpoint returns 503 with extra.reason = "search_unavailable". The structured feed and every other endpoint are unaffected: retry the search later rather than the whole chain.

get/api/news/search/

Query parameters

qstring required
Example:Jane Street

The words to search for, 2 to 200 characters (syntax above). query is accepted as an alias.

cursorstring

Opaque cursor from a prior response's next_cursor; only valid with the q that issued it.

symbolstring
Example:NVDA

Hard ticker filter, same forms and expansions as on /api/news/ (ticker is an alias).

categoryNewsCategory[]

Hard category filter — single value, CSV or repeated, OR-matched.

source_typestring[]

Keep only rows ingested from these sources, same values and forms as on /api/news/: gdelt (press coverage), sec_form4, sec_form8k, sec_form6k. Single, CSV or repeated, OR-matched. Unknown values return 400.

itemstring
Example:5.02

8-K item code, e.g. 5.02: only 8-K filings carrying that item (any item of the filing). Implies source_type=sec_form8k; next to any other source_type it returns 400.

min_relevanceinteger

Override the default ≥4 threshold.

page_sizeinteger

Items per page, default 10; 1-20 on every tier, up to 50 on a Pro key (limit is an alias).

collapse'story'

story collapses coverage of one event to its best-ranked article, with story_id, sources_count and sources on each item.

from_datestring date-time

Inclusive lower bound on time_published (ISO-8601, UTC when naive; a bare date is that day's midnight). Past your archive horizon → 403.

to_datestring date-time

Inclusive upper bound on time_published; a bare date covers its whole day.

Response

A page of ranked matches.

next_cursorstring nullable

Pass back as cursor for the next page; null past the 200-match bound.

countinteger required

Items on this page.

matchedinteger required

Visible matches in the bounded candidate set (at most 200); never a global total.

Example response

{
  "results": [
    {
      "enrichment": {
        "tickers": [
          "NVDA"
        ],
        "news_context_enhancement": {
          "key_entities": [
            {
              "type": "company"
            }
          ]
        }
      },
      "earnings": {
        "fiscal_period": "Second Quarter Fiscal 2027",
        "key_metrics": [
          {
            "value": "$96.2 billion",
            "numeric": 96.2,
            "unit": "USD"
          }
        ]
      },
      "story_id": "788e477c66f3849b",
      "sources_count": 3,
      "sources": [
        "reuters.com",
        "apnews.com",
        "bloomberg.com"
      ],
      "insider": {
        "transaction_code": "S",
        "shares": "25000",
        "avg_price_usd": "187.32",
        "total_value_usd": "4683000",
        "insider_name": "STEVENS MARK A",
        "insider_title": "Director",
        "transaction_date": "2026-07-09",
        "filed_at": "2026-07-11T20:31:04Z"
      },
      "filing": {
        "items": [
          "5.02",
          "9.01"
        ],
        "primary_item": "5.02",
        "accession_number": "0001193125-26-231145",
        "filed_at": "2026-09-18T20:05:12Z",
        "event_date": "2026-09-16",
        "exhibit_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000123/ex99-1.htm"
      }
    }
  ]
}

Changes

Changed in 1 of the 16 revisions of this API.1