` for italics, `` for code blocks. HTML entities are
unescaped for you (`/` becomes `/`, `"` becomes `"`), but the tags
themselves are left in place, because stripping them would destroy the
paragraph breaks. Strip them yourself if you want plain text.
- **A missing field is `null`, never `0` or `""`.** Hacker News does not score
individual comments, so `points` on a comment is always `null` — a zero there
would read as a measurement that was never made. Likewise a text post has no
`url`, and a link post has no `story_text`.
- **A single query reaches at most 1000 items.** The search API pages through
the first 1000 hits of any one query and then returns nothing, however the
pages are sliced; `hitsPerPage` above 1000 is silently clamped. `maxItems`
above 1000 therefore needs several narrower queries, or a date range walked
in slices, to go further back. Both limits were measured on 2026-08-24.
- **Items are de-duplicated by `objectID`** before they are delivered, so the
same story matching two of your queries is emitted and billed once.
- No rate limiting was observed in testing (40 requests back to back all
returned HTTP 200), but the actor still treats HTTP 429, 403 and 5xx as
transient and retries them with backoff. A malformed filter, which the API
answers with HTTP 400, is treated as permanent and is not retried.
### Billing
One event per delivered item, charged after the item is written to the dataset:
`post-scraped` for stories and `comment-scraped` for comments. The event is
chosen from what each item actually is, not from what was requested, so a mixed
search bills each row correctly. A small `actor-start` event covers the fixed
cost of a run that legitimately finds nothing.
# Actor input Schema
## `queries` (type: `array`):
Keywords to search Hacker News for. Each query is searched separately and the results are merged and de-duplicated. Leave empty to browse by tag alone, for example the current front page.
## `tags` (type: `array`):
Restrict results to these kinds of item. Several tags are combined with AND, so 'story' plus 'show\_hn' means Show HN submissions only. Leave empty to return both stories and comments.
## `sortBy` (type: `string`):
Relevance ranks by how well an item matches the query, which is what the Hacker News search box does by default. Date returns the newest items first and ignores relevance entirely.
## `minPoints` (type: `integer`):
Only return items with at least this many points. Hacker News does not score individual comments, so setting this while searching comments returns nothing.
## `startDate` (type: `string`):
Only return items created on or after this date. Accepts YYYY-MM-DD, a full ISO 8601 timestamp, or a Unix timestamp in seconds.
## `endDate` (type: `string`):
Only return items created on or before this date. A bare YYYY-MM-DD date includes the whole of that day. Accepts the same formats as the start date.
## `maxItems` (type: `integer`):
Stop after this many items in total, across all queries. The search API only pages through the first 1000 hits of any single query, so use several narrower queries or a date range to reach further back.
## `proxyConfiguration` (type: `object`):
Proxy used for the search requests. The Hacker News search API needs no proxy and no login, so this is only worth enabling if your runs are being rate limited.
## Actor input object example
```json
{
"queries": [
"python"
],
"tags": [
"story"
],
"sortBy": "relevance",
"maxItems": 100,
"proxyConfiguration": {
"useApifyProxy": false
}
}
```
# Actor output Schema
## `items` (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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"queries": [
"python"
]
};
// Run the Actor and wait for it to finish
const run = await client.actor("superslowsloth/hacker-news-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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = { "queries": ["python"] }
# Run the Actor and wait for it to finish
run = client.actor("superslowsloth/hacker-news-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 '{
"queries": [
"python"
]
}' |
apify call superslowsloth/hacker-news-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,superslowsloth/hacker-news-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 ` 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/Nj40ZDUD2WuDSFdZ6/builds/wJVGHta1m14fiemTB/openapi.json