GET /health

Is the service up, and how many articles does it hold right now.

bash

curl "https://freenewsapi.ai/health"

response

{"status": "ok", "documents": 118276}

Response

200 with status: "ok" — search backend reachable, documents is the live count.
503 with status: "degraded" — the API is up but the search backend is not answering. Retry with backoff; do not hammer.

What each state means

ok means the API process is running and it got an answer from the search cluster. It is not a claim that the data is fresh — a stalled ingest pipeline still reports ok, because search itself is working. Freshness is a separate question, answered by snapshots.

degraded means the API answered but the cluster behind it did not. Search requests will be failing with 503. This is the state to alert on: it is unambiguous, it is machine-readable, and it does not depend on parsing an error message.

No response at all means the API process or the host is down. Treat a timeout the same as degraded, with a longer backoff.

Using it as a health check

Two properties make this endpoint suitable for a monitor: it touches the real dependency rather than just returning 200 from a static handler, and it is cheap enough to call repeatedly. Once a minute is comfortable; once a second is abuse of a free service.

A useful check verifies more than the status code. The document count should be non-zero and should grow over a day — a count that is flat for several hours means ingest has stopped even though search is fine:

python

import requests

def check(previous=None):
    r = requests.get("https://freenewsapi.ai/health", timeout=10)
    if r.status_code != 200:
        return "down", None
    d = r.json()
    if d.get("status") != "ok":
        return "degraded", None
    n = d["documents"]
    if previous is not None and n == previous:
        return "stale", n          # search works, ingest may have stopped
    return "ok", n

Notes

The count is a live query, not a cached number. It is cheap, but it is not free.

The number moves in steps, not smoothly: roughly a hundred thousand articles arrive in one hourly batch, and older ones fall out of the 30-day window continuously. A count that goes down is normal — it means retention deleted more than the last batch added.

This endpoint has no filters and no parameters. For a breakdown of what those documents are, use /v1/stats. For pipeline freshness — when the last batch landed and how big it was — see snapshots.