# Hacker News Scraper — Search Stories & Comments (`puskin/hn-scraper`) Actor

Search and retrieve Hacker News stories, comments, and user info via the free Algolia Search API. No API key required — filter by points, date, tags, and more.

- **URL**: https://apify.com/puskin/hn-scraper.md
- **Developed by:** [Giovanni Bucci](https://apify.com/puskin) (community)
- **Categories:** Developer tools, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## HN Scraper

Search and retrieve Hacker News stories, comments, and user data via the free Algolia Search API — **no API key required**.

### Features

- **Search Stories** — Full-text search across all HN stories. Filter by tags (story, show\_hn, ask\_hn, front\_page), minimum points, and date range
- **Get Story** — Fetch a single story with its full comment tree (nested threads preserved)
- **Get User** — List all stories submitted by a specific HN user

### Input

| Field      | Type    | Default      | Description                                      |
|------------|---------|--------------|--------------------------------------------------|
| mode       | select  | `searchStories` | `searchStories`, `getStory`, `getUser`        |
| query      | string  | —            | Keyword for story search                         |
| storyId    | int     | —            | Story ID for getStory mode                       |
| username   | string  | —            | HN username for getUser mode                     |
| sort       | select  | `byDate`     | `byDate` (newest) or `byRelevance`               |
| tags       | string  | `story`      | Comma-separated tags: story, comment, ask\_hn, show\_hn, poll, front\_page |
| minPoints  | int     | 0            | Minimum points filter                            |
| limit      | int     | 20           | Max results (1–100)                              |

### Output

Each result is pushed as a JSON record to the Apify dataset.

**searchStories / getUser** — objectID, title, url, author, points, num\_comments, created\_at, story\_text

**getStory** — type ("story" or "comment"), id, title/author, text, points, created\_at, depth (for nested comments), parent\_id, story\_id

### Use Cases

- Track mentions of your product, brand, or technology
- Find popular Show HN launches in your space
- Monitor competitor discussions and sentiment
- Build datasets for NLP or trend analysis
- Research what's trending in tech

### Automation & Integration

- **Schedule daily searches** via Apify's built-in scheduler — track keywords over time
- **Connect to Make.com, Zapier, or n8n** via Apify integrations
- **Export to Google Sheets, Slack, or Discord** from the Apify dataset
- **Alert on mentions** by combining scheduled runs with webhook outputs

### Technical

- Built with Python + httpx
- Uses Algolia Search API at `hn.algolia.com/api/v1`
- Comment trees are flattened with depth markers for easy analysis
- The Algolia API is free, no authentication required

# Actor input Schema

## `mode` (type: `string`):

What to scrape from Hacker News

## `query` (type: `string`):

Keyword or phrase to search for (used in searchStories mode)

## `storyId` (type: `integer`):

Hacker News story ID (used in getStory mode — fetches story + full comment tree)

## `username` (type: `string`):

Hacker News username (used in getUser mode)

## `sort` (type: `string`):

Sort results by date or relevance (searchStories mode only)

## `tags` (type: `string`):

Filter by tag type: story, comment, ask\_hn, show\_hn, poll, front\_page. Comma-separated for AND logic.

## `minPoints` (type: `integer`):

Only return stories with at least this many points (searchStories mode only)

## `limit` (type: `integer`):

Maximum number of results to return (1–100)

## Actor input object example

```json
{
  "mode": "searchStories",
  "query": "Rust programming",
  "storyId": 33786502,
  "username": "pg",
  "sort": "byDate",
  "tags": "story,show_hn",
  "minPoints": 0,
  "limit": 20
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "searchStories",
    "query": "",
    "storyId": 0,
    "username": "",
    "sort": "byDate",
    "tags": "story",
    "minPoints": 0,
    "limit": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("puskin/hn-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "searchStories",
    "query": "",
    "storyId": 0,
    "username": "",
    "sort": "byDate",
    "tags": "story",
    "minPoints": 0,
    "limit": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("puskin/hn-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "searchStories",
  "query": "",
  "storyId": 0,
  "username": "",
  "sort": "byDate",
  "tags": "story",
  "minPoints": 0,
  "limit": 20
}' |
apify call puskin/hn-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=puskin/hn-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/4i6AOvMZxo2ZmX7io/builds/V7JbHQGdcOiI83bD8/openapi.json