# Hacker News Scraper - Search Stories & Comments (`northglasslabs/hackernews-scraper`) Actor

Search Hacker News stories using the free Algolia HN API. Returns story titles, points, authors, URLs, comment counts, and creation dates. No authentication or browser required — pure JSON API with zero bot-detection risk.

- **URL**: https://apify.com/northglasslabs/hackernews-scraper.md
- **Developed by:** [North Glass Labs](https://apify.com/northglasslabs) (community)
- **Categories:** Social media, Developer tools
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hacker News Scraper — Search Stories, Points & Comments

Quickly search and extract **Hacker News** stories via the free Algolia HN Search API. Get story titles, URLs, authors, upvote points, comment counts, and creation dates as structured JSON. The actor uses HTTPS requests rather than a browser.

### What it does

The Hacker News Scraper actor searches and retrieves stories from Hacker News (Y Combinator's social news site) using the free **Algolia HN Search API**. It talks directly to a public JSON API rather than rendering web pages.

Each story returned includes the title, external URL, author handle, upvote points, comment count, creation timestamp, the story's self-text, Algolia's `objectID`, and associated tags. Self-posts have an empty `url`; use `objectId` to identify the HN item. Results can be sorted by relevance or newest first.

This makes the actor ideal for tech sentiment monitoring, competitive intelligence, link-bait research, and building datasets of what the developer community is discussing on any topic — from new programming languages and AI tools to startup launches and security vulnerabilities.

### Input parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `searchQuery` | string | ✅ Yes | — | The text to search for in Hacker News stories. Must not be empty. |
| `maxResults` | integer | No | `50` | Maximum number of stories to retrieve (1–1000). |
| `sortBy` | string | No | `relevance` | Sort order. One of: `relevance` or `date_desc` (newest first). |

### Output fields

Each result item pushed to the dataset contains:

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Story title as shown on Hacker News |
| `url` | string | External URL linked from the story (empty for self-posts) |
| `author` | string | Hacker News username of the story submitter |
| `points` | integer | Upvote count (karma points) the story has received |
| `numComments` | integer | Number of comments on the story |
| `createdAt` | string | ISO-8601 timestamp of when the story was posted |
| `objectId` | string | Algolia object ID (unique identifier for the story in the HN index) |
| `storyText` | string | Self-text of the story (populated for "Ask HN" / "Show HN" posts; empty for link posts) |
| `tags` | array of strings | Tags associated with the story (e.g. `["story"]`) |

### Use cases

- **Tech trend monitoring** — track what developer communities are discussing about new frameworks, AI models, or product launches
- **Sentiment analysis** — collect story titles and points to gauge community reception of a topic
- **Competitive intelligence** — find discussions mentioning your competitors or industry keywords
- **Content curation** — build newsletters, blog roundups, or social media posts from top HN stories
- **Link-building research** — identify popular URLs being shared in your niche for outreach
- **Data collection** — assemble datasets of HN activity for NLP, research, or market analysis

### How it works

The actor calls the **Algolia HN Search API**. When `sortBy` is `relevance`, it uses `https://hn.algolia.com/api/v1/search`. When `sortBy` is `date_desc`, it uses `https://hn.algolia.com/api/v1/search_by_date`, which returns newest-first results. The actor requests stories only (`tags=story`) and up to `maxResults` hits. Each hit is mapped to the nine documented output fields and pushed to the default dataset.

### Example usage

#### Example input

```json
{
    "searchQuery": "Rust programming language",
    "maxResults": 10,
    "sortBy": "date_desc"
}
```

#### Example output

```json
{
    "title": "Why Rust is the most loved programming language",
    "url": "https://blog.rust-lang.org/2025/01/15/Rust-survey.html",
    "author": "jnordan",
    "points": 452,
    "numComments": 189,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "objectId": "39871234",
    "storyText": "",
    "tags": ["story"]
}
```

### Pricing

This actor uses the **pay-per-event (PPE)** pricing model on Apify. You are charged a small fee for each successful actor run. Because the Hacker News Scraper uses a free public API and does not launch a browser, runs are extremely fast and cost-efficient — typically completing in under 5 seconds. Check the actor's Apify Store page for the current per-run pricing. Apify's free tier includes monthly platform credits that are sufficient for hundreds of searches.

### Tips

- **Use specific queries for relevance sorting** — broad queries like "AI" will return the all-time top stories; narrow queries like "GPT-4 API pricing" return more targeted results.
- **Use `date_desc` for recent discussions** — sort newest-first to monitor recent matching stories.
- **Increase `maxResults` for broad topics** — the API supports up to 1,000 results per query. For niche topics, fewer than 50 results may exist, so the default is a good starting point.

# Actor input Schema

## `searchQuery` (type: `string`):

The text to search for in Hacker News stories.

## `maxResults` (type: `integer`):

Maximum number of stories to retrieve (1-1000).

## `sortBy` (type: `string`):

Sort order for results.

## Actor input object example

```json
{
  "searchQuery": "artificial intelligence",
  "maxResults": 50,
  "sortBy": "relevance"
}
```

# Actor output Schema

## `results` (type: `string`):

Hacker News stories stored in the default dataset

# 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 = {
    "searchQuery": "artificial intelligence"
};

// Run the Actor and wait for it to finish
const run = await client.actor("northglasslabs/hackernews-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 = { "searchQuery": "artificial intelligence" }

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

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

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

```

## CLI example

```bash
echo '{
  "searchQuery": "artificial intelligence"
}' |
apify call northglasslabs/hackernews-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,northglasslabs/hackernews-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3WagauZlOkJJSMSkp/builds/GSSLKoELURlLaCv0W/openapi.json