Skip to main content

News Feeds Concepts

Core concepts and terminology for understanding the News Feeds API.

What is a News Feed?​

A news feed is a container that aggregates articles from multiple sources into a single stream. You create feeds, attach sources to them, and retrieve the collected articles through the API.

Core Entities​

Feed​

A feed is your primary resource. It holds configuration and serves as the container for all collected content.

Key properties:

  • Unique identifier
  • Name and description
  • Enabled/disabled state

A feed doesn't do anything on its own. You must add sources to it to start collecting content.

Source​

A source defines where content comes from. Each source is attached directly to a feed and tells the system what to monitor.

Source types:

  • Site: Monitor an entire domain for articles
  • Sitemap: Track a specific XML sitemap for new URLs
  • Index Page: Watch a page that lists articles (e.g., a news homepage)

When you add a source, the system begins monitoring it for new content. Historical content from the past 14 days is automatically backfilled.

Item​

An item represents a single article in your feed. When the system discovers and processes an article from a source, it becomes an item in your feed.

Item data includes:

  • Article title and content
  • Original URL
  • Publication date
  • Source information
  • Extracted metadata (images, author, etc.)
  • Relevance score (when filtering is applied)
  • Sentiment analysis (when enabled)

How It Works​

  1. Create a feed - Your container for content
  2. Add sources - Define where to collect articles from
  3. Automatic monitoring - Sources are continuously checked for new content
  4. Content extraction - Articles are processed to extract structured data
  5. Items appear - Processed articles become available through the API

Content Moderation​

Feeds can optionally filter inappropriate content. When enabled, articles are checked against content policies before being added to your feed.

Source Behavior​

  • Each source belongs to a single feed
  • Multiple sources can be added to one feed
  • Removing a source stops new content from that source
  • Existing items from a removed source remain in the feed

Backfilling​

When you add a source, the system automatically retrieves and processes articles from the past 14 days. This populates your feed with recent content immediately, rather than starting from an empty state.