Social Fetch
Get API key
Hacker News hub

Hacker News Story API

Resolve a numeric HN story id to title, score, URL, and comment metadata — with typed lookupStatus when the id is missing or not a story.

GET /v1/hackernews/stories/{id}

1 credit per successful request.

Try in playgroundFull API docs

About this endpoint

Launch trackers, brand monitors, and research desks often land on a news.ycombinator.com item URL and need the story card before they pull the thread: title, author, points, outbound link, and comment count. Treating every id as a story fails when the id is a comment, poll option, or deleted row.

`GET /v1/hackernews/stories/{id}` is the story-shaped lookup. Pass the numeric id, send `x-api-key`, and branch on `data.lookupStatus` before you write a row. On `found`, `data.story` carries id, author, createdAt, title, text, url, score, commentCount, childIds, dead, deleted, and itemUrl. `not_found` means the id does not exist; `not_story` means the id resolved to a non-story item. HTTP 200 still means the request finished.

Credit pricing for this operation comes from the API registry and appears on this page, and `meta.creditsCharged` is the billing source of truth. For any item type, use the polymorphic items route; for the comment tree, use the story comments list.

Hacker News Story API FAQ

How do I fetch a Hacker News story by id?

Call GET /v1/hackernews/stories/{id} with your Social Fetch API key in the x-api-key header. The id is the numeric HN item id from the item URL. Read data.lookupStatus, then data.story.

How many credits does a Hacker News story lookup cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.

What does lookupStatus mean on story lookup?

found means data.story is populated. not_found means the id does not exist. not_story means the id exists but is not a story (for example a comment or job). Always branch on lookupStatus before treating the payload as a found story.

Story route vs items route?

GET /v1/hackernews/stories/{id} requires a story-shaped item and returns not_story otherwise. GET /v1/hackernews/items/{id} returns any item type with a type field. Use stories when your pipeline assumes a story card; use items when the id may be a comment, poll, or job.

Does this return the comment tree?

No. This endpoint returns the story card and top-level childIds. To page the comment tree, use GET /v1/hackernews/stories/{id}/comments.

Does HTTP 200 always mean the story was found?

No. HTTP 200 means the request finished. Check data.lookupStatus: found, not_found, or not_story. Persist meta.requestId when you need to debug a miss.

Can I use this for monitoring or enrichment jobs?

Yes. Teams hydrate story cards from search or feed hits, refresh score and commentCount on a schedule, and only fan out to comments when discussion depth matters.

Other Hacker News endpoints