Skip to content
scrapeatlas.Dashboard

Developer communities

Hacker News API

Read the ranked Hacker News front page, search stories and comments by relevance or date, retrieve a story, read its comment tree, and look up user profiles.

5 endpointsx-api-key

Search Hacker News by relevance or date, list the ranked front page, and retrieve profiles, stories and nested comment trees, preserving fields, nulls and coverage.

API availability: Available

Base URL · local workerhttp://localhost:3015Public API: https://api.scrapeatlas.com.
Authenticationx-api-keyCustomer key from your account. See Authentication.

Endpoints

GET/v1/hackernews/search

Search Hacker News

Search Hacker News by relevance or by date. Use tags to select stories, comments, polls, Show HN, Ask HN, front-page items or an author; query is optional when tags or numericFilters select the results, so a tags-only request returns the current front page or one author’s items. Filter timestamps and counts with numericFilters, restrict matching to chosen attributes, disable typo tolerance for exact matching, and select a results page.

Reference
GET/v1/hackernews/stories

List ranked Hacker News stories

List the item IDs of a ranked Hacker News list in source rank order: top (the front page), new, best, Ask HN, Show HN or jobs. IDs are returned as data; read the ones you want with the story endpoint. Page through the list with limit and page.

Reference
GET/v1/hackernews/story

Get a Hacker News story

Retrieve one Hacker News item by numeric ID: title, submitted URL, author, points, self-post text, poll options and creation time, with the IDs of its direct child comments. Set includeCounts to add the live score and total comment count from the official API. The item type is returned; comment IDs are accepted and return that comment. Use the comments endpoint for the nested discussion.

Reference
GET/v1/hackernews/story/comments

Get a Hacker News story’s comments

Retrieve a nested Hacker News comment tree with comment fields and children. Bound the walk with depth and limit to read only the levels you need. Deleted comments retain null author and text values, and coverage describes the returned tree.

Reference
GET/v1/hackernews/profile

Get a Hacker News profile

Retrieve a public Hacker News user from the official API by case-sensitive username: karma, account creation time, the about text when present, and the count of submitted items.

Reference

Quick start

Create an API key on your account page, then call the public API. Values below are placeholders.

Terminal
curl "https://api.scrapeatlas.com/v1/hackernews/search?query=claude+code&tags=story&numericFilters=created_at_i%3E1756684800&sortBy=date&hitsPerPage=30&page=0" \
  -H "x-api-key: YOUR_API_KEY"

Coverage & limits

  • Independent, stateless worker: four concurrent operations; 20-second total deadline; at most three upstream HTTP attempts per operation (two source reads plus one shared transient retry). Only story with includeCounts reads twice. No automatic retry for challenges or HTTP 429.
  • Fixed public HTTPS origins only: hn.algolia.com for search and items, hacker-news.firebaseio.com for users, ranked story lists and live item counters. No login, cookies, browser, proxy, outbound link visits, media downloads or result storage. The service API key is never forwarded.
  • At most 8 MiB decoded JSON, depth 128 and 400,000 nodes per source response. Oversize or malformed responses fail explicitly.
  • Search: one source page of 1–100 hits, default 30, pages 0–999; the source serves up to 1,000 hits per query, so deep result sets are read by moving a created_at_i window with numericFilters. Tags default to story. Relevance ordering is the source’s; sortBy=date returns newest first.
  • Ranked lists: top and new hold up to 500 IDs, best 200, and Ask HN, Show HN and jobs fewer. IDs are returned in rank order without item fields; read them with the story endpoint.
  • Story and comments: one source thread read each. Comment trees return up to 5,000 nodes, then comment_limit partial coverage; depth and limit bound the walk and report depth_limit. Story child ID lists truncate at 5,000 with children_limit. A story’s num_comments in search can exceed the returned tree because the source counts removed comments.
  • Profiles: the official API’s id, created, karma and about are preserved; the submitted list is summarised as submittedCount. A user’s items are read with search and tags=author_<username>. Usernames are case-sensitive.
  • Source caching and live counters can affect freshness.
Error codes
11
HTTPfailure.codeMeaning
200partialUsable data with comment_limit, depth_limit, children_limit or counts_unavailable warnings.
400invalid_requestMissing, duplicate, malformed or unsupported parameters, including a search that selects nothing.
401unauthorizedMissing or invalid worker API key.
404not_foundThe source reports a missing item or user.
429upstream_rate_limitedSource throttling; no automatic retry.
502upstream_challengedSource rejected the unauthenticated request.
502unsupported_pageMalformed, mismatched or non-JSON source data.
502response_too_large payload_too_complexResponse exceeded byte or parsing limits.
502unsafe_redirect request_limit upstream_errorBounded source retrieval could not complete.
503busyAll worker slots are occupied.
504timeoutTotal request deadline expired.