CheckRSS

CheckRSS › Guides

Feed status badge and API

Show visitors that your feed is alive, or run the checker from a script. Both are free and need no key.

Status badge

The badge is a small image that says whether your feed address answers and returns a feed. It is checked again about once an hour.

RSS feed: online

HTML

<a href="https://checkrss.com/?url=https://example.com/feed.xml">
  <img src="https://checkrss.com/api/badge?url=https://example.com/feed.xml"
       alt="Feed status" height="20">
</a>

Markdown

[![Feed status](https://checkrss.com/api/badge?url=https://example.com/feed.xml)](https://checkrss.com/?url=https://example.com/feed.xml)

Replace https://example.com/feed.xml with the address of your feed. If the address contains ? or &, encode it first (the checker's result page gives you a ready snippet).

Badge saysMeaning
onlineThe address answers with status 200 and the content is a feed.
HTTP 404 (or another code)The server answered with an error status.
not a feedThe address works but returns something else, usually a web page.
timeout / unreachableThe server did not answer in time, or could not be reached.

The badge is a quick liveness test. It does not run the full validation, so a feed with warnings still shows as online.

JSON API

GET https://checkrss.com/api/check?url=ADDRESS

ADDRESS is a feed or a website. For a website the feed is discovered first and the first feed found is checked. Example:

curl "https://checkrss.com/api/check?url=https://xkcd.com/rss.xml"

Response

{
  "ok": true,
  "status": "warnings",
  "url": "https://xkcd.com/rss.xml",
  "summary": { "status": "warnings", "errors": 0, "warnings": 1, "infos": 0, "passed": 9 },
  "feed": {
    "format": "RSS", "version": "2.0", "title": "xkcd.com",
    "link": "https://xkcd.com/", "language": "en",
    "itemCount": 4, "isPodcast": false,
    "lastItemAt": "2026-11-13T05:00:00.000Z", "avgIntervalHours": 56
  },
  "items": [ { "title": "…", "link": "…", "date": "…", "guid": "…" } ],
  "checks": [
    { "level": "warning", "group": "feed", "id": "no-self-link",
      "title": "The feed does not state its own address", "detail": "…" }
  ],
  "http": { "status": 200, "finalUrl": "…", "redirects": [], "contentType": "text/xml; charset=UTF-8", "ms": 140 },
  "checkedAt": "2026-11-14T21:00:00.000Z"
}
FieldMeaning
oktrue when a feed was found and has no errors.
statusvalid, warnings, invalid, not-a-feed, no-feed-found or error.
checks[].levelerror, warning, info or pass. The id is stable and safe to match on. All checks are described on the list of checks.
discoveredFrom, candidatesSet when you passed a website: the page the feed was found on and all feeds found there.
itemsThe ten newest items.
errorWith status: "error": a code (such as timeout, unreachable, bad-host) and a readable message.

Limits

  • The API analyses the first 512 KB of a feed. Larger feeds are cut there and the complete items are checked. The checker on the site handles feeds up to 25 MB.
  • Results are cached for two minutes.
  • Only public addresses on ports 80 and 443 are fetched.
  • There is no key and no hard quota, but the service is small. Please keep automated use to a few requests a minute. Heavy use may be limited without notice.
  • Cross-origin requests are allowed, so the API can be called from a browser.

Questions

Can I use the API to monitor my feed?

Yes. Call it from a scheduled job every hour or so and alert when ok is false. Checking more often than every few minutes returns the cached result anyway.

Can I use the badge in a GitHub README?

Yes. Use the Markdown snippet above. GitHub caches images on its own servers, so the badge there may lag behind by some hours.

What does the feed's server see?

A request with the user agent CheckRSS/1.0 (+https://checkrss.com/bot/). More on the fetcher page.