Media, Film & Knowledge

Hacker News API

The Hacker News API returns stories, comments and user data as clean JSON.

9 actionsLive JSON1,000 free creditsMCP-ready

🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.

The primary item endpoint returns a story or comment (id, type, author, time, title/text/url, score and kids), and you can pull a full comment tree, a user, story lists, search, a poll, the front page, updates and the max item id. It is built for tech-news apps, community analytics and research tools that need HN data with hydrated comment trees. One ReefAPI key, one shared credit pool, the standard envelope.

Live example

Real request and response JSON

Captured from the indexed primary action, search, on Jul 18, 2026, 5:19 PM UTC.

Captured request

{
  "method": "POST",
  "url": "https://api.reefapi.com/hackernews/v1/search",
  "headers": {
    "x-api-key": "$REEF_KEY",
    "content-type": "application/json"
  },
  "body": {
    "query": "python",
    "tags": "story"
  }
}

Captured response

{
  "ok": true,
  "meta": {
    "api": "hackernews",
    "endpoint": "search",
    "mode": "live",
    "latency_ms": 1112.9,
    "record_count": 20,
    "bytes": 29495,
    "cache_hit": false,
    "completeness_pct": 100,
    "requests": 1,
    "nbHits": 539834,
    "nbPages": 50,
    "page": 0,
    "sort": "relevance"
  },
  "data": {
    "hits": [
      {
        "id": 45751400,
        "type": "story",
        "title": "Uv is the best thing to happen to the Python ecosystem in a decade",
        "url": "https://emily.space/posts/251023-uv",
        "author": "todsacerdoti",
        "points": 2214,
        "num_comments": 1324,
        "text": null,
        "story_id": 45751400,
        "parent_id": null,
        "created_at": "[redacted-phone]T18:57:29Z",
        "created_at_i": 1761764249,
        "tags": [
          "story",
          "author_todsacerdoti",
          "story_45751400"
        ],
        "hn_url": "https://news.ycombinator.com/item?id=45751400"
      },
      {
        "id": 20915746,
        "type": "story",
        "title": "Sunsetting Python 2",
        "url": "https://www.python.org/doc/sunset-python-2/",
        "author": "azizsaya",
        "points": 1616,
        "num_comments": 704,
        "text": null,
        "story_id": 20915746,
        "parent_id": null,
        "created_at": "[redacted-phone]T06:43:24Z",
        "created_at_i": 1568011404,
        "tags": [
          "story",
          "author_azizsaya",
          "story_20915746"
        ],
        "hn_url": "https://news.ycombinator.com/item?id=20915746"
      },
      {
        "id": 13319904,
        "type": "story",
        "title": "Grumpy: Go running Python",
        "url": "https://opensource.googleblog.com/2017/01/grumpy-go-running-python.html",
        "author": "trotterdylan",
        "points": 1411,
        "num_comments": 451,
        "text": null,
        "story_id": 13319904,
        "parent_id": null,
        "created_at": "[redacted-phone]T17:00:39Z",
        "created_at_i": 1483549239,
        "tags": [
          "story",
          "author_trotterdylan",
          "story_13319904"
        ],
        "hn_url": "https://news.ycombinator.com/item?id=13319904"
      }
    ],
    "count": 20,
    "nbHits": 539834,
    "page": 0,
    "nbPages": 50,
    "hitsPerPage": 20,
    "query": "python",
    "processingTimeMS": 12,
    "sort": "relevance"
  }
}

Actions

What the Hacker News API does

Action	Description	Concrete use case	Key params
item	single item by id (story/comment/job/poll/pollopt) — all official fields + time_iso/kids_count/hn_url; hydrate_kids=resolve top-level comments	Content platforms call item to get single item by id (story/comment/job/poll/pollopt).	id, hydrate_kids, kids_limit
item_tree	full nested comment TREE for a story in ONE call; recursive children + descendants count	Research tools call item_tree to get full nested comment TREE for a story in ONE call; recursive children + descendants count.	id
user	user profile by id: karma/created/about/submitted; hydrate_submitted=resolve recent submissions	Community analysts call user to get user profile by id.	id, hydrate_submitted, submitted_limit
stories	story-list (list=top/new/best/ask/show/job) → ranked hydrated stories; offset/limit pagination, hydrate=false for ids only	Media monitors call stories to get story-list (list=top/new/best/ask/show/job) → ranked hydrated stories; offset/limit paginatio….	list, limit, offset, hydrate
search	Full-text search: query + tags(story/comment/ask_hn/show_hn/poll/front_page/author_X/story_X) + min_points/max_points/min_comments/before/after + sort(relevance\|date), paginated	Content platforms call search to get full-text search.	query, tags, sort, page, hits_per_page, ...
poll	Poll detail by id: the question + every voting option resolved and ranked by votes, with total_votes and the comment count. (Find poll ids via search with tags=poll.)	Research tools call poll to get poll detail by id.	id
front_page	Stories that recently made the Hacker News front page (newest-first), paginated. Optional after/before date window. NOTE: the front-page index only retains ~the last 7 days — it is 'what's on / recently hit the front page', not a historical archive.	Community analysts call front_page to get stories that recently made the Hacker News front page (newest-first), paginated.	limit, page, after, before
updates	live changefeed: recently changed item ids + profiles + max_item; hydrate=resolve changed items	Media monitors call updates to get live changefeed.	hydrate, limit
max_item	the current largest item id on Hacker News — the newest id, useful for backfilling / id-range walks	Content platforms call max_item to get the current largest item id on Hacker News.	none

Code samples

Call search from your stack

curl -X POST https://api.reefapi.com/hackernews/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"python","tags":"story"}'

import requests

r = requests.post(
    "https://api.reefapi.com/hackernews/v1/search",
    headers={"x-api-key": REEF_KEY},
    json={
  "query": "python",
  "tags": "story"
},
)
print(r.json()["data"])

const res = await fetch("https://api.reefapi.com/hackernews/v1/search", {
  method: "POST",
  headers: {
    "x-api-key": process.env.REEF_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
  "query": "python",
  "tags": "story"
}),
});
const { ok, data, meta, error } = await res.json();

MCP one-liner

Ask your MCP-connected assistant: call reefapi.hackernews.search with {"query":"python","tags":"story"}.

Use cases

Who uses this API and why

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.

FAQ

Questions developers ask before integrating

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.

Is the Hacker News API a Hacker News scraper?

It is the managed alternative to a DIY Hacker News scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same stories, comments, users and full-text search back as clean JSON.

Why does my Hacker News scraper keep getting blocked?

Most Hacker News scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.

docs / hackernews

Hacker News

Stories, comments, users and full-text search.

base /hackernews/v19 endpoints

post/hackernews/v1/item1 credit

single item by id (story/comment/job/poll/pollopt) — all official fields + time_iso/kids_count/hn_url; hydrate_kids=resolve top-level comments

Parameter		Allowed / range	Description
id	required	—	HackerNews item id (story/comment/job/poll/pollopt) — the digits in an item URL (news.ycombinator.com/item?id=...).
hydrate_kids = false	optional	—	If true, resolve the item's top-level comments into full objects instead of bare ids.
kids_limit = 30	optional	1–100	When hydrate_kids=true, how many top-level comments to resolve (1-100).

Try in playground →

post/hackernews/v1/item_tree1 credit

full nested comment TREE for a story in ONE call; recursive children + descendants count

Parameter		Allowed / range	Description
id	required	—	HackerNews item id (story/comment/job/poll/pollopt) — the digits in an item URL (news.ycombinator.com/item?id=...).

Try in playground →

post/hackernews/v1/user1 credit

user profile by id: karma/created/about/submitted; hydrate_submitted=resolve recent submissions

Parameter		Allowed / range	Description
id	required	—	HackerNews username (case-sensitive), e.g. 'pg'.
hydrate_submitted = false	optional	—	If true, resolve the user's recent submissions into full objects instead of bare ids.
submitted_limit = 20	optional	1–100	When hydrate_submitted=true, how many recent submissions to resolve (1-100).

Try in playground →

post/hackernews/v1/stories2 credits

story-list (list=top/new/best/ask/show/job) → ranked hydrated stories; offset/limit pagination, hydrate=false for ids only

Parameter		Allowed / range	Description
list = top	optional	top · new · best · ask · show · job	Which HackerNews story list to return.
limit = 30	optional	1–100	Stories to return (1-100, default 30). Out-of-range values are clamped.
offset = 0	optional	0–500	Pagination offset into the story list (0-500). Skip N ranked stories.
hydrate = true	optional	—	If true, resolve each ranked story id into full objects instead of bare ids (default true).

Try in playground →

post/hackernews/v1/search1 credit

Full-text search: query + tags(story/comment/ask_hn/show_hn/poll/front_page/author_X/story_X) + min_points/max_points/min_comments/before/after + sort(relevance|date), paginated

Parameter		Allowed / range	Description
query	optional	—	Full-text search keywords. search needs query OR tags.
tags	optional	—	Tag filter. Built-ins: story, comment, ask_hn, show_hn, poll, front_page. Dynamic: author_USERNAME, story_ID. Comma-joins = AND, (a,b) = OR. search needs query OR tags.
sort = relevance	optional	relevance · date	Result ordering: relevance (default) or date (newest first). Any non-date value is treated as relevance.
page = 0	optional	0–50	0-based search results page (0-50). Page forward via meta.nbPages.
hits_per_page = 20	optional	1–100	Search results per page (1-100, default 20).
min_points	optional	0–	Minimum score (points) filter for search hits.
max_points	optional	0–	Maximum score (points) filter for search hits.
min_comments	optional	0–	Minimum comment-count filter for search hits.
max_comments	optional	0–	Maximum comment-count filter for search hits.
before	optional	—	Only hits created on/before this date. Accepts a unix timestamp or an ISO date (YYYY-MM-DD).
after	optional	—	Only hits created on/after this date. Accepts a unix timestamp or an ISO date (YYYY-MM-DD).
numeric_filters	optional	—	Advanced: raw Algolia numericFilters string, appended to the built min/max/date filters (e.g. 'points>100,created_at_i>1700000000').
restrict	optional	—	Advanced: restrictSearchableAttributes — limit matching to given Algolia fields (e.g. 'title' or 'title,story_text').

Try in playground →

post/hackernews/v1/poll1 credit

Poll detail by id: the question + every voting option resolved and ranked by votes, with total_votes and the comment count. (Find poll ids via search with tags=poll.)

Parameter		Allowed / range	Description
id	required	—	HackerNews poll id (the digits in a poll's item URL). Find polls with the search action using tags=poll.

Try in playground →

post/hackernews/v1/front_page1 credit

Stories that recently made the Hacker News front page (newest-first), paginated. Optional after/before date window. NOTE: the front-page index only retains ~the last 7 days — it is 'what's on / recently hit the front page', not a historical archive.

Parameter		Allowed / range	Description
limit = 30	optional	1–100	Front-page stories to return (1-100, default 30). Out-of-range values are clamped.
page = 0	optional	0–50	0-based search results page (0-50). Page forward via meta.nbPages.
after	optional	—	Only front-page stories created on/after this date (unix ts or YYYY-MM-DD). Note: the front-page index only retains ~the last 7 days.
before	optional	—	Only front-page stories created on/before this date (unix ts or YYYY-MM-DD).

Try in playground →

post/hackernews/v1/updates1 credit

live changefeed: recently changed item ids + profiles + max_item; hydrate=resolve changed items

Parameter		Allowed / range	Description
hydrate = false	optional	—	If true, resolve the changed item ids into full objects instead of bare ids.
limit = 30	optional	1–100	Changed items to hydrate (1-100, default 30). Out-of-range values are clamped.

Try in playground →

post/hackernews/v1/max_item1 credit

the current largest item id on Hacker News — the newest id, useful for backfilling / id-range walks

Try in playground →

Example request · item

curl -X POST https://api.reefapi.com/hackernews/v1/item \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"id":8863}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}