RSS, Atom & JSON Feed Change Monitor for Agents

Use this RSS change monitor to turn RSS, Atom, JSON Feed, or ordinary website URLs into a stateful, versioned change stream. Every run returns feed-health evidence and only emits item records that are new or changed after the stored baseline.

This Actor is designed for agents, scheduled automations, ETL jobs, and monitoring systems that need stable JSON rather than another one-time feed parser.

Use from an MCP client

Connect only this Actor through Apify's remote MCP server:

https://mcp.apify.com?tools=xerophylous_mercy_0wn/feed-contract-monitor

Authenticate with Apify OAuth or a bearer token. The scoped URL keeps tool discovery focused and exposes the Actor's input and output contracts to compatible agent clients.

What it does

• Parses RSS 2.0, RSS 1.0/RDF, Atom 1.0, and JSON Feed 1.0/1.1.
• Discovers feeds from standard HTML <link rel="alternate"> elements.
• Sends If-None-Match and If-Modified-Since on later runs when publishers provide ETag or Last-Modified.
• Stores a bounded baseline in a named Apify key-value store.
• Emits new and changed item records with deterministic fingerprints and delivery IDs.
• Reports malformed feeds, duplicate IDs, invalid dates, stale feeds, redirects, HTTP failures, and output limits with stable issue codes.
• Never scrapes linked article pages. Content comes only from the feed itself.
• Rejects private-network, loopback, link-local, authenticated, and non-HTTP targets.

Quick start

Use a direct feed URL:

{
  "feedUrls": ["https://www.nasa.gov/feed/"],
  "firstRunMode": "emit_recent",
  "maxInitialItems": 20
}

Or give it websites and let it discover their declared feeds:

{
  "feedUrls": [
    "https://example.com/",
    "https://another.example/news"
  ],
  "discoverFromWebsites": true,
  "stateNamespace": "production-news"
}

For a clean monitoring baseline without historical output:

{
  "feedUrls": ["https://example.com/feed.json"],
  "firstRunMode": "baseline_only"
}

Schedule later runs with the same stateStoreName and stateNamespace.

Dataset contract

The default dataset contains two record types. Both are charged as visible dataset results under Apify pay-per-event pricing.

Feed-health record

One health record is emitted for every checked feed. Website discovery adds one additional discovery health record.

{
  "schemaVersion": "feed-health/1.0",
  "recordType": "feed_health",
  "sourceUrl": "https://www.nasa.gov/feed/",
  "feedUrl": "https://www.nasa.gov/feed/",
  "feedTitle": "NASA",
  "feedFormat": "rss-2.0",
  "checkedAt": "2026-08-04T15:00:00.000Z",
  "status": "ok",
  "httpStatus": 200,
  "itemCounts": {
    "seen": 10,
    "new": 3,
    "changed": 0,
    "unchanged": 7,
    "emitted": 3,
    "deferred": 0,
    "remembered": 10
  },
  "conditionalRequest": {
    "etagUsed": true,
    "lastModifiedUsed": false,
    "notModified": false
  },
  "stale": false,
  "issues": []
}

Changed-item record

{
  "schemaVersion": "feed-item/1.0",
  "recordType": "feed_item",
  "sourceUrl": "https://example.com/feed.json",
  "feedUrl": "https://example.com/feed.json",
  "feedTitle": "Example research feed",
  "feedFormat": "json-feed-1.1",
  "checkedAt": "2026-08-04T15:00:00.000Z",
  "status": "new",
  "changeType": "new",
  "deliveryId": "77248d...",
  "itemId": "paper-123",
  "url": "https://example.com/papers/123",
  "title": "A new result",
  "summary": "Publisher-supplied excerpt",
  "contentText": null,
  "authors": ["Example Author"],
  "tags": ["chemistry"],
  "publishedAt": "2026-08-04T13:00:00.000Z",
  "modifiedAt": null,
  "fingerprint": "f7b5ac...",
  "sourcePointer": "items[0]",
  "issues": []
}

The run summary is also stored as SUMMARY in the run's default key-value store.

Delivery semantics

Delivery is at least once. A process can stop after a dataset write but before its baseline update, so downstream systems should deduplicate with deliveryId. The ID is stable for the same feed URL, item ID, and item fingerprint. A corrected item receives a new delivery ID and changeType: "changed".

Missing items are not reported as deletions because most feeds are rolling windows. Items deferred by maxItemsPerRun remain eligible on a later run.

Content modes

• metadata: IDs, links, titles, dates, authors, and tags only.
• excerpts (default): metadata plus a truncated publisher-supplied summary.
• feed_content: excerpts plus truncated text supplied inside the feed.

The Actor does not visit item links, bypass access controls, or retrieve authenticated content.

Persistent state

The default named store is feed-contract-monitor-state. Each feed has one hashed state record containing:

• ETag and Last-Modified values;
• last successful and last checked timestamps;
• feed format and final URL;
• bounded item IDs, fingerprints, and seen timestamps.

Use stateNamespace to keep independent baselines for development, production, or different consumers. State is capped by maxStateItemsPerFeed; the most recently seen entries are retained.

Stable issue codes

Range	Meaning
FCM001–FCM010	URL, DNS, network, redirect, size, and encoding failures
FCM100–FCM103	Unsupported or malformed feed/discovery documents
FCM110–FCM116	Feed and item quality warnings
FCM200–FCM202	State or output-limit warnings

Every issue includes code, severity, message, and an optional source pointer. Codes remain stable within contract version 1.x.

Cost controls

• 256 MB default memory and 512 MB hard maximum.
• Bounded response size, retries, redirects, state, output, and concurrency.
• Conditional requests when the publisher supports them.
• No browser runtime or proxy use.
• One visible health result per checked feed, even when no item changed.

Set a run maximum cost in Apify when using large URL batches. Publication uses pay per event so the Actor remains available to API and agentic consumers.

Current limitations

• HTML discovery uses declared alternate links; it does not execute JavaScript.
• Non-UTF-8 feeds may contain replacement characters.
• Publisher-specific formats outside RSS, Atom, RDF/RSS, and JSON Feed are not inferred.
• Feed removals are not treated as item deletions.
• Availability and correctness ultimately depend on the publisher's endpoint.

Output and schema versions

• Feed items: feed-item/1.0
• Feed health: feed-health/1.0
• Persistent state: feed-state/1.0
• Run summary: feed-monitor-run/1.0

Minor releases may add optional fields or issue codes. Breaking field changes require a new major contract version.