# Hacker News Trends and Stories (author-free) (`orlibachar/hn-trends`) Actor

Hacker News front-page, new, best, Ask, Show and job stories, keyword search, and keyword/domain trend summaries from the official HN API and the HN Search API. Author handles and text are never included.

- **URL**: https://apify.com/orlibachar/hn-trends.md
- **Developed by:** [ORLIBACHAR Ltd](https://apify.com/orlibachar) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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 Trends and Stories (author-free)

Get Hacker News stories as clean rows, or summarise what HN is talking about by keyword or by linked domain.

- **Story lists:** top, new, best, Ask HN, Show HN and jobs, in HN's own ranking order.
- **Keyword search:** stories matching a query, newest first, with date and score filters.
- **Trends:** one row per keyword or per domain with story count, total points, total comments, average points and the highest-scoring stories.

The Actor reads two public APIs that need no key and no login: the official Hacker News API and the HN Search API. It does not use a browser or a proxy and runs in 256 MB.

This Actor is independent. It is not made, endorsed or supported by Y Combinator, Hacker News or Algolia.

### What it does not return

No author usernames, no story or comment text, no comment threads and no user profiles. Every output row is built from a fixed list of keys.

Story titles and URLs are returned as published. A title can itself mention a person.

### Input

| Field | Type | Meaning |
|---|---|---|
| `mode` | text | `top`, `new`, `best`, `ask`, `show`, `job`, `search` or `trends`. Default `top`. |
| `query` | text | Required for `search`. |
| `trendBy` | text | `domain` (default) or `keyword`. Trends only. |
| `keywords` | list | One trend row per keyword (`trendBy` = `keyword`). |
| `dateFrom` / `dateTo` | YYYY-MM-DD | Story date window in UTC. `dateTo` is inclusive. Trends default to the last 7 days. |
| `minScore` | number | Keep stories with at least this many points. |
| `maxItems` | number | Stop after this many rows. Default 50. |
| `includeCommentCounts` | yes/no | Fill comment counts. Default yes. |
| `topStoriesPerTrend` | number | Stories listed inside each trend row. Default 3. |
| `maxStoriesScanned` | number | Stories read per keyword (or in total for domain trends). Default 1000. |

Examples:

```json
{ "mode": "top", "maxItems": 30 }
```

```json
{ "mode": "search", "query": "rust", "minScore": 50, "dateFrom": "2026-10-15", "maxItems": 100 }
```

```json
{ "mode": "trends", "trendBy": "keyword", "keywords": ["rust", "golang", "zig"], "dateFrom": "2026-11-01", "dateTo": "2026-11-13" }
```

#### How the modes work

- **List modes** read HN's current list (up to 500 ids for top/new, up to 200 for ask/show/job) and fetch each story. Date and score filters are applied to the fetched stories, so a strict filter may return fewer rows than `maxItems`. Deleted and dead items are skipped. Jobs usually have no score, so they drop out when `minScore` is above 0.
- **Search** asks the HN Search API for stories, newest first. Date and score filters are applied by the API.
- **Trends** read up to `maxStoriesScanned` stories (newest first) in the window and add them up. If the limit is hit, the row says `truncated: true` and only covers the newest stories in the window. Domain trends put text posts without a link under `(text post, no link)`.

### Output

Story rows (list and search modes):

| Key | Meaning |
|---|---|
| `id` | HN item id |
| `url`, `domain` | Linked URL and its host without `www.` (empty for text posts) |
| `title` | Story title |
| `type` | `story`, `job` or `poll` |
| `score` | Points |
| `commentCount` | Number of comments |
| `time` | Posted at, UTC, ISO 8601 |
| `hnUrl` | Link to the HN discussion |
| `rank` | Position in the HN list, or in the search results |

Trend rows (trends mode):

| Key | Meaning |
|---|---|
| `trendType`, `key` | `keyword` or `domain`, and the keyword or domain |
| `storyCount`, `totalPoints`, `totalComments`, `avgPoints` | Totals over the stories read |
| `topStories` | Highest-scoring stories: `id`, `title`, `url`, `score`, `commentCount`, `hnUrl` |
| `window` | The `from` / `to` dates used |
| `minScore` | Score filter used |
| `approxMatches` | Keyword trends: match count reported by the search API (may be approximate) |
| `truncated` | `true` if `maxStoriesScanned` was reached |
| `rank` | Position in this run's output |

### Pricing

Pay per row written to the dataset: one price for story rows, a higher one for trend rows. See PRICING.md (not final until a measured test run).

### Limits

- Scores and comment counts change over time. Each row is a snapshot at run time.
- Keyword matching is done by the HN Search API. It can match words in the URL or other indexed text, not only the title.
- Search pages move backward in time, so they are not limited to Algolia's page depth. If more than 100 stories share the exact same second, some of them can be missed.
- List modes make one request per story. Pauses: 0.05 s between stories, 0.4 s between search pages. Rate-limit and server errors are retried with backoff.

### Data sources

- Official Hacker News API: https://github.com/HackerNews/API
- HN Search API: https://hn.algolia.com/api

# Actor input Schema

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

top/new/best/ask/show/job read the official HN lists (top and new hold up to 500 ids, ask/show/job up to 200). 'search' finds stories by keyword. 'trends' returns one summary row per keyword or per domain.

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

Required for mode 'search'. In 'trends' by keyword it is used as the keyword if 'Keywords' is empty.

## `trendBy` (type: `string`):

Mode 'trends' only. 'domain' = one row per linked domain in the window. 'keyword' = one row per keyword below.

## `keywords` (type: `array`):

Mode 'trends' by keyword: one summary row per keyword.

## `dateFrom` (type: `string`):

Earliest story date, YYYY-MM-DD. In 'trends' the default is the last 7 days.

## `dateTo` (type: `string`):

Latest story date, YYYY-MM-DD.

## `minScore` (type: `integer`):

Keep only stories with at least this many points. 0 = no filter. In list modes, items without a score (often jobs) are dropped when this is above 0.

## `maxItems` (type: `integer`):

Stop after this many rows. Each row written to the dataset is one charged event.

## `includeCommentCounts` (type: `boolean`):

Fill commentCount / totalComments. Comment text is never included.

## `topStoriesPerTrend` (type: `integer`):

How many highest-scoring stories to list inside each trend row.

## `maxStoriesScanned` (type: `integer`):

Upper limit of stories read per keyword (or in total for domain trends). Rows show truncated=true when the limit was hit.

## Actor input object example

```json
{
  "mode": "top",
  "trendBy": "domain",
  "keywords": [],
  "minScore": 0,
  "maxItems": 50,
  "includeCommentCounts": true,
  "topStoriesPerTrend": 3,
  "maxStoriesScanned": 1000
}
```

# Actor output Schema

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

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("orlibachar/hn-trends").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("orlibachar/hn-trends").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 '{}' |
apify call orlibachar/hn-trends --silent --output-dataset

```

## MCP server setup

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

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/3LMAMp7PwyKrfcsUK/builds/tqT6iQLVaaVrC0i1Z/openapi.json
