The comment tree in one call, not two hundred
The Hacker News API returns stories, comments and user data as clean JSON.
9 active endpoints, on 1 and 2 credit tiers.
- POST/hackernews/v1/item
- POST/hackernews/v1/item_tree
- POST/hackernews/v1/user
- POST/hackernews/v1/stories
- POST/hackernews/v1/search
- POST/hackernews/v1/poll
- POST/hackernews/v1/front_page
- +2 more
What Hacker News endpoints does ReefAPI ship?
9 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Hacker News API
3 of 9 endpoints, ready to run
A ranked list — top, new, best, ask, show or jobs — already hydrated with title, URL, score, author, time and comment count.
{ "ok": true, "meta": { "api": "hackernews", "endpoint": "stories", "mode": "live", "latency_ms": 3095.6, "record_count": 30, "cache_hit": false, "completeness_pct": 100 }, "data": { "list": "top", "stories": [ { "id": 49489982, "type": "story", "by": "pluc", "time": 1788012130, "time_iso": "2026-08-29T14:02:10Z", "title": "Debian votes to allow \"responsible use of generative AI\"", "url": "https://lwn.net/Articles/1091231/", "text": null, "score": 64, "descendants": 32, "parent": null, "poll": null, "parts": null, "kids": [ 49490252, 49490382, 49490290 ], "kids_count": 11, "deleted": false, "dead": false, "hn_url": "https://news.ycombinator.com/item?id=49489982", "rank": 1 }, { "id": 49487341, "type": "story", "by": "ingve", "time": 1787983611, "time_iso": "2026-08-29T06:06:51Z", "title": "Samsung's Processing-in-Memory (PIM)", "url": "https://chipsandcheese.com/p/hot-chips-2026-samsungs-processing", "text": null, "score": 171, "descendants": 54, "parent": null, "poll": null, "parts": null, "kids": [ 49489515, 49488944, 49488558 ], "kids_count": 22, "deleted": false, "dead": false, "hn_url": "https://news.ycombinator.com/item?id=49487341", "rank": 2 }, { "id": 49490138, "type": "story", "by": "uecker", "time": 1788013233, "time_iso": "2026-08-29T14:20:33Z", "title": "Indirect Calling of Nested Functions on GCC Without Executable Stack", "url": "https://uecker.codeberg.page/2026-08-29.html", "text": null, "score": 4, "descendants": 0, "parent": null, "poll": null, "parts": null, "kids": [], "kids_count": 0, "deleted": false, "dead": false, "hn_url": "https://news.ycombinator.com/item?id=49490138", "rank": 3 } ], "count": 30, "total": 500, "offset": 0, "max_available": 500, "stop_reason": "limit_reached" } }
How the Hacker News API works
Hacker News is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 184 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Watching for a mention without polling the front page
The official interface hands out ids and expects one request per item, which turns 'read the top thirty' into thirty-one requests and a comment thread into hundreds.
{"query": "your product", "tags": "story", "min_points": 50}The point filter is what separates a mention that mattered from a submission nobody saw.
{"id": 8863}Then the whole discussion, nested, in one call — which is the difference between reading a thread and building a crawler.
Story lists come back hydrated, so the ranked list and the item fields are one call rather than one plus thirty.
curl -X POST https://api.reefapi.com/hackernews/v1/stories \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"list":"top","limit":15}'{
"ok": true,
"data": { … },
"meta": {
"api": "hackernews",
"endpoint": "stories",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}Two field vocabularies for the same Hacker News data
This engine speaks two dialects. The official item feed uses by, score, time and kids; the search-backed surfaces use author, points, created_at and children. The same story comes back with different key names depending on which action you called, which is the biggest source of undefined values here. Measured 2026-08-26 and 2026-08-27 on item 8863, the 2007 Dropbox post, plus live front-page data.
| What you want | item, stories, poll, user, updates | search, front_page, item_tree |
|---|---|---|
| Author | by | author |
| Points | score | points |
| Comment count | descendants | num_comments on search and front_page; descendants on item_tree |
| Direct replies | kids[] plus kids_count | children[] plus children_count |
| Timestamp | time (unix seconds) plus time_iso | created_at (ISO 8601) plus created_at_i (unix seconds) |
| Parent | parent | parent_id |
| Owning story | not returned | story_id, which equals id on the story itself |
| Measured on item 8863 | score 104, descendants 71, kids_count 33 | points 104, descendants 71, children_count 32 |
kids_count 33 against item_tree's 32 direct children is not an arithmetic error: the tree drops dead and deleted replies that the official kids array still lists. Treat kids_count as an upper bound on what a tree walk will hand you.
What the hydration and the search actually save
Measured on ranked lists and search.
The upstream returns ids; this returns the items. Reading the top thirty is one call instead of thirty-one, and the response reports the total available and why it stopped.
A discussion is a tree and the official interface makes you walk it a node at a time. One call returns it nested, from the story id alone.
Minimum points and minimum comments are query parameters. On this site the score is the entire signal, and being able to say 'only things above fifty points' upstream is what makes a monitoring job cheap.
Items carry explicit deleted and dead flags. A comment tree with silently missing nodes is confusing; one that says a node was removed is honest, and it lets you decide how to render it.
Unix time and an ISO string on every item. Small thing, but it removes the conversion step from every consumer of this data.
What people build with Hacker News
The jobs this data is most often used for.
endpoints
credits per call
Tech-news apps call stories and front_page to show the current Hacker News ranking.
Community-analytics tools use item_tree to analyze full discussion threads at once.
Research products use search and user to track topics and contributors over time.
What Hacker News data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 184 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/hackernews/v1/stories \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"list":"top","limit":15}'import requests
r = requests.post(
"https://api.reefapi.com/hackernews/v1/stories",
headers={"x-api-key": REEF_KEY},
json={
"list": "top",
"limit": 15
},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up Hacker News.
Get a free key →What is the difference between score, descendants and kids_count?▾
score is upvotes, descendants is every comment anywhere under the story, and kids_count is only the direct replies. Item 8863 measured on 2026-08-27 returned score 104, descendants 71 and kids_count 33. item_tree on the same story returned 71 records with direct_children 32, one fewer than kids_count, because the tree omits a reply the kids array still lists. On a comment, score and descendants are both null: only stories, jobs and polls carry them.
Why do item and item_tree use different field names for the same thing?▾
They come from two different Hacker News surfaces. item, stories, poll, user and updates follow the official item shape (by, score, time, time_iso, kids), while item_tree, search and front_page follow the search index shape (author, points, created_at, created_at_i, children, parent_id, story_id). The table above maps them. If a field reads undefined, the usual cause is reading by off a search hit, or author off an item.
Which fields are null for each item type?▾
The shape is uniform and the differences are explicit nulls, so you can branch on type safely. A link story has text null and url set. An Ask HN story is the reverse: url null and text carrying the body, measured on two current Ask HN posts. A comment has title, url, score and descendants all null, with parent set. A job has descendants null and kids an empty array, because jobs take no comments, and both measured jobs had score 1.
How do I tell a dead item from a deleted one?▾
Two separate booleans, and they hollow out different fields. Measured on 2026-08-26: item 49456664 came back dead true, deleted false, with by still "sona-coffee11", time intact and text set to the literal string "[flagged]". Item 49456656 came back deleted true, dead false, with by null and text null, keeping only id, type and time. Both returned ok:true with a full record, so filter on the flags rather than expecting an error.
What does the poll action return, and is score the vote count?▾
No, a poll carries two separate numbers. Poll 126809 measured 2026-08-27 returned score 47, which is upvotes on the poll itself, and total_votes 301, which is the sum of its three options at 179, 73 and 49. descendants 54 is the comment count, a third number again. options[] is ranked by votes and each option is a real pollopt item with its own id and hn_url, while parts[] lists the same option ids in the poll's original order.
How far back does front_page go?▾
About seven days. The front-page index is a rolling window of what recently hit the front page rather than an archive, and meta returns a window_note saying so. A request for an older date range comes back thin or empty rather than erroring. For anything historical use search with tags=front_page combined with before and after, and accept that the same retention limit applies to that tag.
How do I walk every item on Hacker News?▾
max_item gives you the current highest id, and ids are dense integers, so you count backwards. It returned 49456670 at 2026-08-26T22:16Z. The updates action gives you the ids that changed most recently plus the profiles that changed, which is the cheap way to keep a mirror fresh instead of rescanning. The list surfaces have ceilings the ids do not: top, new and best hold up to 500 entries, ask, show and job up to 200, and search is paged 0 to 50.
Is the text field plain text or HTML?▾
HTML, with entities left encoded. Measured bodies contain paragraph breaks as literal <p> tags and apostrophes as ', for example "We've been building open source embedded ADS-B receivers". Unescape entities and handle the tags before you index or display it. Titles are plain, and hn_url is always present so you can link back to the item without building the URL yourself.
What is the Hacker News API?▾
Hacker News API is a ReefAPI endpoint group for stories, comments, users and full-text search. It returns live JSON through POST requests under /hackernews/v1.
Is the Hacker News API free to try?▾
Yes. ReefAPI starts with 1,000 free credits, no card required. Hacker News calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Hacker News login or account?▾
No login to Hacker News is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Hacker News data?▾
The page example is captured from a live item call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Hacker News API use?▾
Hacker News actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Hacker News from an AI assistant or MCP client?▾
Yes. Connect ReefAPI once through MCP and your assistant can call hackernews actions with the same key, credit pool and JSON envelope used by normal REST requests.
25 Media, Film & Knowledge APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Hacker News, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 183 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-30.