Coverage passport — what each data source holds, from when, with which caveats

One object per data source: publisher_news (the GDELT stream, RSS feeds and directly parsed publisher pages), sec_form4, sec_form8k, sec_form6k, earnings_reads, earnings_schedule and economic_calendar. Each carries its earliest and latest row, the last ingest time, the row count in the source's own unit, the collector's cadence, a history note saying where the history is thin, the known limits, and the per-plan archive horizon. Read this before backtesting or promising coverage downstream: first_row_at is the earliest row we hold, NOT the start of dense coverage — history_note says which months are thin (publisher news densified in June 2026; Form 4 before May 2026 is an unenriched replay; 8-K history starts June 2026; 6-K and earnings reads start 2026-07-28).

The passport is computed once a day (03:50 UTC) and served from a cache: as_of is when the counts were taken and generated_at when the payload was assembled, so both describe the computation, never the response. Rows may be up to a day newer than last_row_at. On a cold cache the first caller computes it (a few seconds); a concurrent caller gets 503 with Retry-After instead of a second scan.

stale is an honest flag, not an alert: true when the newest ingest is older than stale_after_seconds — six poll cycles for the collectors, three days for SEC filings (EDGAR takes no filings on weekends), ten days for earnings reads — or, for the economic calendar (stale_after_seconds null), when no future occurrence is held. publisher_news additionally reports each discovery channel (gkg, rss) with its own last ingest and flag. research_only restates that everything described here is AI-generated financial information for research, not investment advice.