Ycombinator APInews.ycombinator.com ↗
Access Hacker News stories, comments, user profiles, job posts, and engagement stats via 9 structured endpoints. Search by keyword, filter by timeframe, and paginate results.
What is the Ycombinator API?
This API exposes 9 endpoints covering Hacker News stories, comments, user profiles, and job listings. The get_top_posts endpoint returns front-page stories across five categories (top, new, best, ask, show) with fields like points, num_comments, author, and time_iso. Other endpoints cover full comment threads, keyword search with timeframe filtering, per-post engagement statistics, and a breakdown of every commenter on a given thread.
curl -X GET 'https://api.parse.bot/scraper/1ad7a614-cdcd-4bd0-87e6-2cc68e58d555/get_top_posts?limit=5&story_type=top' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace news-ycombinator-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Hacker News SDK — bounded, re-runnable; every call capped."""
from parse_apis.Hacker_News_API import HackerNews, StoryType, SearchSort, Timeframe, TrendingTimeframe, CommentSort, ItemNotFound
hn = HackerNews()
# List top stories from the front page
for post in hn.posts.list(story_type=StoryType.TOP, limit=5):
print(post.title, post.points, post.num_comments)
# Search for posts about "rust" sorted by date in the last week
for post in hn.posts.search(query="rust", sort_by=SearchSort.DATE, timeframe=Timeframe.LAST_7D, limit=5):
print(post.title, post.author, post.time_iso)
# Trending stories about AI in the last 3 days
for post in hn.posts.trending(domain="AI", timeframe=TrendingTimeframe.LAST_3D, limit=3):
print(post.title, post.points)
# Look up a user profile with typed error handling
try:
user = hn.users.get(username="pg")
print(user.username, user.karma, user.created_iso)
except ItemNotFound as exc:
print(f"User not found: {exc}")
# Drill into a post's nested comments via sub-resource
post = hn.post(id=48463808)
for comment in post.comments.list(limit=3):
print(comment.author, comment.text[:80], comment.depth)
# Flat paginated comments filtered by author
for comment in post.flat_comments.list(author="simonw", sort_by=CommentSort.NEWEST, limit=3):
print(comment.author, comment.time_iso, comment.story_title)
# Compute engagement statistics
engagement = hn.engagements.compute(story_type=StoryType.BEST, timeframe=Timeframe.LAST_30D)
print(engagement.total_posts_analyzed, engagement.stats.points.mean, engagement.stats.comments.median)
print("exercised: posts.list / posts.search / posts.trending / users.get / post.comments.list / post.flat_comments.list / engagements.compute")
Get stories from Hacker News by category. Returns formatted story data including title, URL, author, points, and comment count. Stories are returned in the same order as the HN front page for the given category.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of stories to return (max 500) |
| story_type | string | Story category to fetch |
{
"type": "object",
"fields": {
"posts": "array of Post objects with id, title, url, author, points, num_comments, time, time_iso, type, text",
"total": "integer count of stories returned",
"story_type": "string category that was queried"
},
"sample": {
"data": {
"posts": [
{
"id": 48469658,
"url": "https://github.com/apple/container/blob/main/docs/container-machine.md",
"text": "",
"time": 1781051341,
"type": "story",
"title": "macOS Container Machines",
"author": "timsneath",
"points": 536,
"time_iso": "2026-06-10T00:29:01+00:00",
"num_comments": 197
}
],
"total": 5,
"story_type": "top"
},
"status": "success"
}
}About the Ycombinator API
Stories and Search
get_top_posts accepts a story_type parameter (top, new, best, ask, show) and returns up to 500 stories in front-page order. Each story object includes id, title, url, author, points, num_comments, time, time_iso, type, and text. search_posts adds keyword search via a query parameter, with optional sort_by (relevance or date), a timeframe filter (e.g. last_7d, last_30d), and 0-indexed pagination returning total_hits and total_pages.
Comments and Commenters
get_post_comments retrieves nested comment threads for a given post_id, returning each comment with id, author, text, time_iso, depth, and recursive children. The response includes total_comments and comments_returned to distinguish thread size from the returned slice. get_comment_details offers a flat, paginated view of the same thread with per-comment parent_id and story_id fields, filterable by author and sortable by newest, oldest, or relevance. get_post_commenters aggregates comment activity per user, returning comment_count, total_replies_received, and the full text of each comment for up to 100 distinct commenters.
Users and Jobs
get_user_info returns a user's karma, about text (may contain HTML), created Unix timestamp, created_iso, and total_submissions. get_job_posts returns up to 200 job listings in reverse chronological order, each with id, title, url, author, time, time_iso, text, and type.
Trending and Stats
get_trending returns stories sorted by points within a chosen timeframe, with optional filtering by domain or topic keyword. The response includes a domain_distribution map showing how many stories came from each domain. get_post_stats computes max, min, median, mean, stdev, and total for both points and comments across up to 500 posts, and surfaces top_by_points and top_by_comments arrays of 10 stories each.
The Ycombinator API is a managed, monitored endpoint for news.ycombinator.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when news.ycombinator.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official news.ycombinator.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track which domains appear most frequently on HN's front page using
domain_distributionfromget_trending. - Build a keyword alert system by polling
search_postswith a fixedqueryandtimeframeoflast_24h. - Identify the most active commenters in a thread using
get_post_commentersfor community analysis. - Pull current tech job listings from
get_job_poststo aggregate with other hiring sources. - Benchmark a story's performance against front-page norms using
get_post_statsfor points and comment distributions. - Retrieve a user's
karma, account age, andtotal_submissionsto qualify HN accounts by seniority. - Extract nested comment trees from
get_post_commentsfor NLP or sentiment analysis pipelines.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Hacker News have an official developer API?+
What does `get_post_stats` actually compute, and when does it use a timeframe vs. a story category?+
get_post_stats calculates max, min, median, mean, stdev, and total for both points and comments across the posts analyzed. When a timeframe parameter is supplied (e.g. last_7d), the story_type field in the response is set to 'search' and stories are pulled from that time window rather than a live category feed. Without a timeframe, it pulls from the specified story_type category.Does `search_posts` return full story text for Ask HN or Show HN posts?+
text field that carries the body text for Ask HN, Show HN, and other self-post types. Link submissions typically return an empty or null text with a populated url instead.Can the API return a user's comment history or submission list?+
get_user_info returns aggregate profile data — karma, about, account creation date, and total_submissions count — but does not return a list of individual submissions or comments. You can fork this API on Parse and revise it to add an endpoint that queries submission or comment history by username.Are there any known limitations with narrow timeframe and domain filters in `get_trending`?+
last_7d or last_30d when filtering by domain.