# Hacker News (/docs/hackernews)



Hacker News [#hacker-news]

Hacker News is a small platform with an outsized signal-to-noise ratio for anything
developer-adjacent: launches, outages, hiring, and the unfiltered opinion underneath them. Four
endpoints cover it — keyword search over the whole archive, one story, its complete comment
tree, and a user profile. All four are 1 credit.

Base URL: `/v1/hackernews/...`

<Callout>
  `page`

   on 

  `/v1/hackernews/search`

   is 

  **0-indexed**

  , unlike every other page-paginated endpoint on this API. Sending 

  `page=1`

   skips the first results rather than returning them.
</Callout>

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header. Stories are
identified by their numeric id, which search returns as the `objectID`.

```bash
# 1. Find the discussion
curl "https://www.socialcrawl.dev/v1/hackernews/search?query=claude%20code&tags=story" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Read the thread underneath it
curl "https://www.socialcrawl.dev/v1/hackernews/story/comments?id=$STORY_ID" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Search [#search]

`GET /v1/hackernews/search?query=…` runs against the Algolia index behind HN's own search, and
it exposes Algolia's filters directly.

`tags` is the important one. It defaults to `story`, and the useful values are `comment`,
`poll`, `show_hn`, `ask_hn`, `front_page`, and `author_<username>` for one person's submissions.
Pass several comma-separated to widen the search — `tags=story,show_hn` — and pass `comment`
when you want to search what people *said* rather than what they posted.

`numericFilters` takes an Algolia expression on `created_at_i`, the Unix timestamp, which is the
only filterable numeric attribute: `numericFilters=created_at_i>1700000000` restricts to stories
after that moment, and several conditions joined by commas are ANDed. No filter is applied by
default.

`hitsPerPage` runs from 1 to 1000 and defaults to 30, and `page` is **0-indexed** here — unlike
most page-paginated endpoints on this API, which start at 1.

```bash
# Show HN launches mentioning "agent", 100 at a time
curl "https://www.socialcrawl.dev/v1/hackernews/search?query=agent&tags=show_hn&hitsPerPage=100&page=0" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Stories, comments and people [#stories-comments-and-people]

`story` returns one submission by id — title, link, author, points, comment count and publish
time. `story/comments` returns the whole discussion as a **nested tree**, each comment carrying
its id, author, text, points, time and its own replies. There is no pagination and no depth
limit: one call returns the thread.

`/v1/hackernews/profile` returns a user by handle — id, username, bio, karma and account
creation date. HN handles are case-sensitive. The site has no follower counts and no post
counts, so those canonical fields come back empty rather than zero.

Endpoints [#endpoints]

<PlatformEndpoints platform="hackernews" />

Read this before you build [#read-this-before-you-build]

**`page` starts at 0.** Search is the exception to the house convention. Sending `page=1` skips
the first results rather than returning them.

**Points and comment counts are snapshots.** HN scores move for hours after posting. If you are
tracking a launch, re-fetch rather than trusting a first read.

**Hacker News is also a `/v1/search/everywhere` source.** If your question is "who is talking
about this anywhere", the [universal search](/docs/search/everywhere.md) covers HN alongside
Reddit, X, YouTube and the rest in one call. Come here when you need the full comment tree or
Algolia's filters.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* All four endpoints are 1 credit
* The story id is the `objectID` on a search hit, and the number in a
  `news.ycombinator.com/item?id=…` URL