Hacker News Monitor & Keyword Alerts

What it does

Monitor public Hacker News items for keywords. Search mode queries Algolia by date. Latest mode reads the official Firebase lists and items. Each run writes matching items to the dataset. Schedule repeated runs with onlyNew to collect alerts as new dataset rows. This Actor does not send notifications.

Input example

{
  "mode": "search",
  "keywords": ["apify", "web scraping"],
  "matchIn": ["title", "text"],
  "lookbackHours": 168,
  "maxItems": 20,
  "onlyNew": false
}

Input fields

Field	Default	Meaning
mode	search	search uses Algolia. latest uses Firebase.
keywords	[]	Match any keyword, case-insensitively. Empty means everything.
matchIn	["title","text"]	Select title, text, or comments. Comment text matches text or comments.
types	All five types	Select story, comment, ask, show, or job.
minPoints	0	Minimum points for non-comment items.
lookbackHours	24	Include items within this age window.
maxItems	200	Maximum matching items per run, from 1 to 10000.
onlyNew	true	Skip IDs saved after successful earlier pushes.
includeCommentsForStories	false	Fetch up to 100 descendants per story. A story can match their text when matchIn includes comments.
stateStoreName	hacker-news-monitor-state	Named key-value store holding the SEEN array of string IDs.

Output sample

{
  "id": 1,
  "type": "story",
  "title": "Apify web scraping & tools",
  "url": "https://example.org/1",
  "text": "Public APIs",
  "author": "alice",
  "points": 42,
  "numComments": 1,
  "createdAt": "2026-10-20T00:00:00.000Z",
  "hnUrl": "https://news.ycombinator.com/item?id=1",
  "parentId": null,
  "storyId": null,
  "matchedKeywords": ["apify", "web scraping"],
  "matchedIn": ["title"],
  "source": "algolia",
  "checkedAt": "2026-10-20T00:01:00.000Z"
}

Text has HTML removed and entities decoded. Missing text fields are empty strings. Missing counts are zero. parentId and storyId can be null. The default key-value store contains RUN_SUMMARY, including timestamps, counts, charging-limit status, and any run error.

How only new works

The Actor deduplicates IDs within each run. With onlyNew, it also skips IDs from earlier successful pushes. Updates to an existing item do not make its ID new. Use a separate state store for each independent monitor.

IDs are saved after a successful dataset push. Failed pushes remain eligible. Dataset writes and state writes are separate operations, so a crash between them can produce duplicates on retry. Avoid overlapping runs that share the same state store. Seen history grows with unique pushed IDs.

Pricing

The pay-per-event price is $0.0005 per item, or $0.50 per 1,000 items, with no run fee. The charging event is item. Skipped records have no item event charge. Local runs do not bill events. Store pricing must be configured separately as described in PUBLISHING.md.

Limits

• Algolia's index can lag behind Hacker News. Search queries use Algolia's search semantics before local keyword filtering. Local matching can reject candidates but cannot recover candidates omitted by Algolia.
• Firebase has no search API. Latest mode scans the current new, ask, show, and job lists. Comments come from those stories, so this is not a complete comment firehose.
• Comment inspection is bounded to 100 descendants per story. Matches beyond that bound can be missed. Comment enrichment uses Firebase even for Algolia stories.
• Keyword matching uses word boundaries around substring phrases. It is case-insensitive and does not perform stemming or semantic matching.
• Requests start at least 100 milliseconds apart per host. API rate limits still apply. HTTP 429 and 5xx responses retry up to three times with backoff and Retry-After. Requests time out after 30 seconds.
• Runs stop at maxItems, exhausted source pages or lists, or the remaining charging allowance. Algolia also limits accessible search pages.

Disclaimer

This Actor is unofficial and is not affiliated with or endorsed by Y Combinator, Hacker News, or Algolia. It uses public documented APIs only. It uses no logos and requires no login.

Local development

Node 20 or newer is required. Tests stub fetch and use local storage.

npm test
NODE_OPTIONS="--import=./test/offline-preload.js" npm start

The second command runs the real Actor with fixture responses and the sample input. Read storage/datasets/default/ and storage/key_value_stores/default/RUN_SUMMARY.json. Normal npm start uses the public APIs.