Social Fetch
Start for freeStart free
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 Failed requests are free

Try in playgroundFull API docs

About this endpoint

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