Hacker News API: List stories
Lists current Hacker News stories in rank order from the top, newest, best, Ask HN, Show HN or jobs list.
Unofficial. Not affiliated with or endorsed by Hacker News.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- List Name optional
list_name Hacker News list to read, for example ask_hn.
top (default)
One of
top,newest,best,ask_hn,show_hn,jobs.- Max Results optional
max_results Maximum number of stories to return, for example 60.
30 (default)
Whole number from 1 to 100.
Input as JSON
{}Output
{ "stories": [ { "age": "4 hours ago", "rank": 1, "title": "Local Wikipedia: Wikipedia, but only for things a half hour walk from you", "author": "sohkamyung", "points": 378, "item_id": 50202285, "posted_at": "2026-10-22T23:01:18Z", "website_link": "https://edjefferson.com/localwiki/" , "comment_count": 99, "website_domain": "edjefferson.com", "discussion_link": "https://news.ycombinator.com/item?id=50202285" }, { "age": "10 hours ago", "rank": 2, "title": "Docker is weird", "author": "psxuaw", "points": 484, "item_id": 50202681, "posted_at": "2026-10-22T23:45:56Z", "website_link": "https://codeandcake.dev/posts/2026-10-22-docker-is-weird" , "comment_count": 219, "website_domain": "codeandcake.dev", "discussion_link": "https://news.ycombinator.com/item?id=50202681" }, { "age": "5 hours ago", "rank": 3, "title": "How does Fable 5.1 hide messages in images?", "author": "gmays", "points": 87, "item_id": 50201445, "posted_at": "2026-10-22T21:41:13Z", "website_link": "https://www.lesswrong.com/posts/WHEQps5PK8LrrcTAb/how-does-fable-5-1-hide-messages-in-images" , "comment_count": 26, "website_domain": "www.lesswrong.com", "discussion_link": "https://news.ycombinator.com/item?id=50201445" } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"news.ycombinator.com/list_front_page","input":{}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "news.ycombinator.com/list_front_page" , "input": {}})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "news.ycombinator.com/list_front_page" , "input": {} }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run news.ycombinator.com/list_front_page# with {}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [], "properties": { "list_name": { "enum": [ "top", "newest", "best", "ask_hn", "show_hn", "jobs" ], "type": "string", "default": "top", "description": "Hacker News list to read, for example ask_hn." }, "max_results": { "type": "integer", "default": 30, "maximum": 100, "minimum": 1, "description": "Maximum number of stories to return, for example 60." } }}Output schema
{ "type": "object", "required": [ "stories" ], "properties": { "stories": { "type": "array", "items": { "type": "object", "required": [ "rank", "title", "discussion_link", "item_id" ], "properties": { "age": { "type": [ "string", "null" ] }, "rank": { "type": "integer" }, "title": { "type": "string" }, "author": { "type": [ "string", "null" ] }, "points": { "type": [ "integer", "null" ] }, "item_id": { "type": "integer" }, "posted_at": { "type": [ "string", "null" ] }, "website_link": { "type": [ "string", "null" ] }, "comment_count": { "type": [ "integer", "null" ] }, "website_domain": { "type": [ "string", "null" ] }, "discussion_link": { "type": "string" } } } } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
news.ycombinator.com/list_front_page- Returns
- rank, title, website link and domain, points, comments, author, posted time, discussion link, item id
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method news.ycombinator.com/list_front_page with the inputs above.
Ask your agent
- What are the top 30 stories on Hacker News right now?
- Show me the 60 newest posts on HN with their points and comment counts
- Pull the best-ranked Hacker News stories this week, including author and posted time
- I need the latest Ask HN questions, around 15 of them, with links to discussion threads
- Can you list the current Show HN projects in rank order with their domains and item ids?
See more
All Hacker News methodsGets a Hacker News story and its comments in the order shown on the site. The story can be given as a discussion link or as words from its title. Deleted and flagged comments are left out.
news.ycombinator.com/get_discussionSearches Hacker News stories or comments by words, date range and sort order. Comments include their parent story's website link when one exists; text-only stories have no website link.
news.ycombinator.com/search_storiesLists top-level job posts from a monthly Ask HN: Who is hiring? thread in thread order, with post text and the company, roles, location, work arrangement, salary and application contact inferred from each post.
news.ycombinator.com/list_hiring_postsSearches the Y Combinator company directory by keyword, industry, batch, location, hiring and status, returning companies in directory order.
ycombinator.com/search_companiesLooks up a Y Combinator company by name or YC company page link and returns its profile, founders, social links and open job count.
ycombinator.com/get_companyLists current New York Times headlines with summaries, authors, images and publication times, in the order shown on the chosen section page (top stories or a section). Video-only items, ads and promotions are left out; times come from the section's feed and may be missing.
nytimes.com/list_headlinesLists Steam's top-selling, discounted, or new and trending games in store order, with prices for a chosen country, review summaries and release dates.
store.steampowered.com/list_top_sellersLists the latest TechCrunch story headlines in a section, in page order. Skips video, podcast and event promotion cards.
techcrunch.com/list_headlines