Execute collection

Execute a collection's sources and return aggregated articles. Fetches from all configured sources, applies filters, merges, and deduplicates results.

Execute is always date-bounded, never silently result-bounded. The window is your date_start/date_end if given, else the collection's saved date range, else the last 30 days. The applied window comes back as date_start/date_end/date_window_source, so a default window is always visible rather than inferred. Results are ordered by published_at descending (newest first, url as tiebreaker) regardless of the collection's merge strategy.

The result cap follows the same precedence as the window: your max_articles, else the collection's stored max_articles_per_refresh, else unbounded — every article in the window. The FTS news source is our own API, so an unbounded execute pages through it, up to a hard ceiling of 5000 articles per query. A cap caps the window rather than replacing it, and it is pushed down to the sources, so total_in_range is bounded by it too: only an uncapped execute reports the true size of the window. Third-party sources (web search) keep their configured per-source limit and vendor caps either way.

There is no offset/cursor pagination — every execute re-fetches live, so there is no stable result set to page over. Two signals tell you the answer was cut short: has_more means your cap bit, and truncated_sources means a source hit its own ceiling with news still unread in the window. For the latter, split the window into calendar chunks that each stay under 5000 and merge the results — see truncated_sources.