# Hacker News (/docs/hackernews)

Hacker News story search with Algolia filters, story detail, full nested comment trees, and user profiles

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, and all four are 1 credit.

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

  `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.

## Quickstart

### 1. Find the discussion

Stories are identified by their numeric id, which search returns as the `objectID`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/hackernews/search?query=claude%20code&tags=story" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Read the thread underneath it

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/hackernews/story/comments?id=38712345" \
  -H "x-api-key: YOUR_API_KEY"
```

One call returns the whole thread. There is no pagination and no depth limit.

## Search the archive

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

| Endpoint                    | Credits | What it returns                                                            | Key parameters                                           |
| --------------------------- | ------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| `GET /v1/hackernews/search` | 1       | Ranked hits from the whole HN archive, each with its `objectID` and points | `query`, `tags`, `numericFilters`, `hitsPerPage`, `page` |

- `tags` defaults to `story`. 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. `page` is 0-indexed.

```bash title="cURL"
# 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: YOUR_API_KEY"
```

## Read a story, its thread, or a person

| Endpoint                            | Credits | What it returns                                                                                      | Key parameters |
| ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- | -------------- |
| `GET /v1/hackernews/story`          | 1       | One submission: title, link, author, points, comment count, publish time                             | `id`           |
| `GET /v1/hackernews/story/comments` | 1       | The whole discussion as a nested tree, each comment with its id, author, text, points, time, replies | `id`           |
| `GET /v1/hackernews/profile`        | 1       | A user by handle: id, username, bio, karma, account creation date                                    | `handle`       |

HN handles are case-sensitive.

## All endpoints

## Platform notes

- **`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.
- **The site has no follower counts and no post counts**, so those canonical fields come back empty on a profile rather than zero.
- **Hacker News is also a universal-search source.** If your question is "who is talking about this anywhere", [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.
- The story id is the `objectID` on a search hit, and the number in a `news.ycombinator.com/item?id=…` URL.

## Next steps

- [Universal search](/docs/search/everywhere.md): One query fanned out across Hacker News, Reddit, X, YouTube and more.
- [Comment schema](/docs/schema/comment.md): The unified shape every comment tree comes back in.
- [Pagination](/docs/pagination.md): Cursor, page, and single-page endpoints across the API.