hackernews-api/search

Hacker News search API — stories by term, with points and comments

Search the public hn.algolia.com index by term. No key, no account, and the same envelope as every other endpoint here.

Parameters

Name	What it is
`q`	The search term. 1 to 80 characters.
`limit`	1 to 100, default 25. Out of range is a 400, never trimmed.

Handle format and anchor

Handle: q (a search term, not a handle)
Anchor: hits is an array

Fields returned

id
title
url
published_at
metrics.points
metrics.comments

What this endpoint does not return.

authorIt is in the Algolia response, it is in the committed fixture on purpose, and it is dropped on the way out. The fixture keeps it so the test can prove the removal — a fixture with the field stripped would make that guard pass by having nothing to look at.
has_moreNull, not false. The index publishes nbPages and our client does not pass it through, so we do not know — and false would promise the list ended.
textStory bodies are not copied. The title, the link and the two counters are what measure a story without reproducing it.

A field we cannot read comes back null, never 0. A zero would be a claim about the account; null is a fact about our collection.

Measured

Measured against the live index on 2026-09-30: `ai agent` in the archiver's own 48-hour window returned 30 items; the same term with the window off and limit=10 returned 10; a term nobody has posted returned HTTP 200 with nbHits 0 and an empty array.

Cost

1 credit per call. A call that finds nothing costs nothing.

Why does a search with no results cost a credit?

Because it is an answer. We searched and there is nothing there — that is information, and it is returned as HTTP 200 with an empty items array. What is never charged is a failed fetch.

Does it search comments too?

No. Titles only, and typo tolerance is off. Both were measured on 2026-09-05: with them on, `mrr` returned 81 results and not one was about MRR — the first five were macOS wallpapers, Nitter instances, a data centre article, Project Xanadu, and US Navy submarine spending.

Other routes for this platform

hackernews-api/story

← hackernews-api