Data Model

Full type signatures are in the API Reference. This page explains what the fields mean.

NewsItem

Field	Type	Meaning
id	string	Stable identity: provider, GUID or link (SEC: accession number), and title joined with |. Versioned by NEWS_ITEM_ID_SCHEME_VERSION
provider	NewsProvider	The provider that produced the record (after merging, the display record's provider)
kind	NewsKind	article, filing, press-release, analysis, video, data, or unknown
title, url, source	string	Headline, link, and publisher name
publishedAt	string?	ISO 8601 UTC instant derived from publishedAtText
publishedAtText	string?	The upstream date text, verbatim. Store it so dates can be re-derived
summary	string?	Description or abstract, when supplied
ticker, companyName, cik	string?	Company identifiers (feed builders fill them from a company subject)
formType, accessionNumber, fileNumber, filingDate, reportDate	string?	SEC filing metadata
relatedTickers	string[]?	Other tickers the item mentions, when supplied
canonicalUrl	string?	Deduplication URL (DOI URLs for many research sources); not set for Google News redirect links
eventKind, tags	optional	Deterministic keyword hints, never sentiment or advice (Company Feeds)
seenInProviders, provenance	optional	Every provider, source, and URL that contributed after merging
research	ResearchPaperMetadata?	Paper metadata (Research Papers)

ResearchPaper is a NewsItem with kind: "analysis" and a required research object.

Dates

parsePublishedAt(text) is the single place date text becomes an instant. It is pure, returns { instant, format } or null, and is versioned by PUBLISHED_AT_PARSER_VERSION (1 in 0.2.2) so stored publishedAtText can be re-derived after a parser fix.

format	Example input
iso_8601	2026-06-02T10:30:00-04:00 (no offset is read as UTC)
date_only	2026-06-02 (midnight UTC)
rfc_822	Tue, 02 Jun 2026 14:30:00 GMT (no zone is read as UTC)
finviz	Jun-02-26 09:15AM (US Eastern)
gdelt	20260602T143000Z
dotnet	/Date(1780410600000)/
engine	Anything else the JavaScript engine can parse; may depend on the host time zone

Invalid explicit dates fail closed (null). Date windows are inclusive, and items without a parseable date are excluded when a window is set.

Subjects and results

• NewsSubjectInput: { kind: "company", ticker?, companyName?, cik? } (at least one identifier) or { kind: "topic", query }.
• NewsSubject (normalized): kind, key (ticker, CIK, or name; or the collapsed query), displayName, and the normalized identifiers.
• ProviderResult: provider, status, capabilities, itemCount, items, undatedExcluded, warnings, fetchedAt, durationMs, requestUrls, error? (message, code?, status?, url?).
• NewsFeedResult: subject, items, providers, warnings, fetchedAt, partial.
• WatchlistNewsFeedResult: subjects ({ subject, result }[]), merged items, flattened providers and warnings, fetchedAt, partial.

Data lane

• DataRelease<Row>: provider, dataset, asOf (YYYY-MM-DD reference date), sequence?, url, updatedAt?, rows.
• DataProviderResult<Row>: provider, dataset, status, release?, rowCount, warnings, fetchedAt, durationMs, requestUrls, error?.
• DataSource<Row>: provider, dataset, requestUrls(options?), fetchRelease(options?) (with ifNewerThan and afterSequence hints).

Events lane

• EventRecord: id (stable within its provider), provider, category, title, severity, and optional summary, url, observedAt, startsAt, endsAt, latitude and longitude (both or neither), magnitude, magnitudeUnit, countryCode, areaName, eventType.
• EventSnapshot: provider, dataset, observedAt, events, warnings, requestUrls.
• EventProviderResult adds status, events, eventCount, fetchedAt, durationMs, error?; EventWatcherResult adds addedEvents.

Works lane

• WorkRecord: provider, sourceId, title, subtitle?, authors, publisher?, publishedYear?, edition?, series?, language?, format?, pageCount?, sizeBytes?, identity, availability, url, addedAt?, modifiedAt?, warnings, provenance.
• WorkIdentity: isbn13?, isbn10?, doi?, oclc?, lccn?, openLibraryId?, md5?, origin (record or resolved), confidence (0–1).
• WorksResult: provider, status, page?, items, recordCount, warnings, fetchedAt, durationMs, requestUrls, error?.

Related

• Errors & Statuses
• Source Catalog