Social Fetch
Get API key
Hacker News hub

Hacker News Item API

Resolve any numeric HN item id to a typed payload — story, comment, job, poll, or poll option — without assuming shape up front.

GET /v1/hackernews/items/{id}

1 credit per successful request.

Try in playgroundFull API docs

About this endpoint

Change polls, favorites lists, and user activity streams hand you bare item ids. You often do not know yet whether the id is a story, comment, job, or poll. A story-only route returns `not_story` and forces a second call; a polymorphic get keeps the pipeline one hop.

`GET /v1/hackernews/items/{id}` is the authoritative item lookup. Pass the numeric id, send `x-api-key`, and branch on `data.lookupStatus`. On `found`, `data.item` includes `type` plus shared fields such as author, createdAt, title, text, url, score, commentCount, parentId, childIds, dead, deleted, and itemUrl when present. `not_found` returns null 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. Prefer the stories route when your code path requires a story card; use items when the type is unknown.

Hacker News Item API FAQ

How do I fetch a Hacker News item by id?

Call GET /v1/hackernews/items/{id} with your Social Fetch API key in the x-api-key header. The id is the numeric HN item id. Read data.lookupStatus, then data.item.type and the rest of the item fields.

How many credits does a Hacker News item 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 item types can this return?

Any public HN item type the upstream API exposes for that id — typically story, comment, job, poll, or pollopt. Always read data.item.type before assuming title, url, or text semantics.

Items vs stories vs comment context?

Items is polymorphic get-by-id. GET /v1/hackernews/stories/{id} requires a story and returns not_story otherwise. GET /v1/hackernews/comments/{id}/context starts from a comment and walks ancestors to the root story.

What does lookupStatus mean on item lookup?

found means data.item is populated. not_found means the id does not exist. Always branch on lookupStatus before writing. Persist meta.requestId when you need to debug a miss.

Does HTTP 200 always mean the item was found?

No. HTTP 200 means the request finished. Check data.lookupStatus. An empty or null item with not_found is a completed typed miss, not a transport failure.

Can I use this after updates or favorites pages?

Yes. Poll GET /v1/hackernews/updates or page favorites/submissions for ids, then hydrate each id with this route. That pattern keeps change detection thin and item shape authoritative.

Other Hacker News endpoints