# Hacker News Data (`onescales/hacker-news-data`) Actor Pull stories, comments, and other items from Hacker News in two flexible ways: browse the live front-page-style category lists (Top, New, Best, Ask, Show, Jobs), or scan every item posted within a specific date and time range. Optionally fetch nested comment threads several levels deep. - **URL**: https://apify.com/onescales/hacker-news-data.md - **Developed by:** [One Scales](https://apify.com/onescales) (community) - **Categories:** AI, Jobs, Social media - **Stats:** 4 total users, 4 monthly users, 100.0% runs succeeded, 3 bookmarks - **User rating**: 5.00 out of 5 stars ## 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/platform/actors/running/actors-in-store#pay-per-usage ## 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use 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 ## Hacker News Data Pull stories, comments, and other items from Hacker News in two flexible ways: browse the live category lists (Top, New, Best, Ask, Show, Jobs), or scan every item posted on a specific date. Optionally fetch nested comment threads several levels deep. ### Introduction This actor queries the official Hacker News API to give you clean, structured access to stories and discussions — no scraping the website required. It works in two modes: - **Category mode**: fetch the current stories in a given HN list (Top, New, Best, Ask HN, Show HN, or Jobs). - **Date mode**: fetch every item (story, comment, job, or poll) posted on one specific UTC day, useful for historical analysis or building an archive. Both modes support fetching nested comment replies to a configurable depth, so you can pull a story with its full conversation tree, not just the top-level comments. ### Features - **Two query modes** — pull the current front page, or scan a specific calendar day. - **Category filtering** — Top, New, Best, Ask HN, Show HN, or Jobs. - **Nested comment threads** — fetch replies up to 5 levels deep, with configurable breadth per level. - **Item type filtering** — in Date mode, narrow results to just stories, comments, jobs, or polls. - **Honest completion signal** — every Date mode run reports `range_complete` so you always know whether you got the whole day or need to page further, instead of silently returning a partial slice. - **Resumable scans** — a `next_page_token` lets you continue a day that had more items than fit in one run. - **HTML-stripped comment text** — comment bodies come back as clean, readable plain text. - **Budget-aware** — automatically caps the number of results returned to stay within any spending limit you've set for the run. ### Use Cases - **Content research** — pull the current top stories on a topic-adjacent category (e.g. Ask HN) for trend analysis or newsletter curation. - **Historical archiving** — scan a specific day of HN activity for research or dataset-building. - **Discussion analysis** — fetch a story along with its full comment tree to analyze sentiment, common themes, or community reaction. - **Monitoring** — periodically pull "New" stories to track when specific topics or domains get submitted. - **Dataset creation** — build a training or evaluation dataset of real-world discussion threads with reply structure intact. ### Input (UI & JSON) The actor has two modes, chosen automatically based on whether you fill in **Date to scan**: - Leave it empty → **Category mode** (pulls current stories from a category list). - Fill it in → **Date mode** (scans every item posted on that one UTC day). | Field | Mode | Description | |---|---|---| | `category` | Category | Which HN list to pull from: `top`, `new`, `best`, `ask`, `show`, or `job`. Default: `top`. | | `date` | Date | The single UTC day to scan, in `YYYY-MM-DD` format (e.g. `2026-07-01`). | | `limit` | Both | Max number of results to return in this run. Default `30`, max `200`. | | `item_type` | Date | Restrict results to `story`, `comment`, `job`, or `poll`. Leave blank for all types. | | `comment_limit` | Category | Number of top-level comments to fetch per story. Default `10`, max `100`, set `0` to skip comments. | | `reply_depth` | Both | How many levels of replies to fetch below each comment. Default `0` (no replies), max `5`. | | `replies_per_comment` | Both | Max replies to fetch per comment at each level. Default `5`, max `20`. Only matters if `reply_depth > 0`. | | `page_token` | Date | Resume token from a previous run's `next_page_token`, used to continue scanning the same day. Leave empty on the first run for a day. | **Example — Category mode (JSON input):** ```json { "category": "top", "limit": 20, "comment_limit": 5, "reply_depth": 1, "replies_per_comment": 5 } ```` **Example — Date mode (JSON input):** ```json { "date": "2026-07-01", "limit": 100, "item_type": "story", "reply_depth": 0 } ``` **Example — continuing a day that wasn't fully scanned:** ```json { "date": "2026-07-01", "limit": 100, "page_token": 48752931 } ``` ### Output (UI & JSON) Results are pushed to the Apify dataset — one row per story (Category mode) or per matched item (Date mode). The **Overview** tab in the dataset UI shows all fields in a table; nested fields like `comments` and `replies` display as expandable JSON. **Common fields (all rows):** | Field | Description | |---|---| | `id` | Hacker News item ID. | | `item_type` | `story`, `comment`, `job`, or `poll`. | | `author` | Username of the poster. | | `posted_at` | Unix timestamp (UTC) when the item was posted. | **Category mode row fields:** | Field | Description | |---|---| | `category` | The category this story was fetched from. | | `title` | Story title. | | `url` | External link, if any. | | `points` | Score. | | `comment_count` | Total number of replies (all levels) on HN. | | `comments` | Array of resolved top-level comments (up to `comment_limit`), each with nested `replies` if `reply_depth > 0`. | **Date mode row fields:** | Field | Description | |---|---| | `title`, `url`, `points`, `comment_count` | Present only on story/job/poll rows. | | `body` | Comment or Ask HN text, HTML-stripped. | | `parent_id` | Parent item ID, for comments. | | `comment_ids` | Raw IDs of direct replies. | | `replies` | Array of resolved replies (if `reply_depth > 0`). | **Run metadata (key-value store, key `OUTPUT`):** Every run also writes a small summary object, separate from the dataset rows: | Field | Applies to | Description | |---|---|---| | `mode` | Both | `get_stories` or `find_by_date`. | | `date` | Date mode | The day that was scanned. | | `count` | Both | Number of rows returned in this run. | | `scanned` | Date mode | Number of raw HN items internally checked. | | `next_page_token` | Date mode | Pass this as `page_token` to continue scanning the same day. `null` if the day was fully covered. | | `range_complete` | Date mode | `true` if this run scanned the entire requested day. `false` means the day had more items than fit in this run — check `next_page_token`. | **Example output row (Category mode):** ```json { "id": 48753715, "category": "top", "item_type": "story", "title": "ZCode – Harness for GLM-5.2", "author": "chvid", "url": "https://zcode.z.ai/en", "points": 234, "posted_at": 1782943416, "comment_count": 223, "comments": [ { "id": 48752128, "author": "seizethecheese", "posted_at": 1782935074, "body": "I'm somewhat surprised that this is not open source...", "reply_count": 9, "replies": [] } ] } ``` **Example run metadata (Date mode, day not fully scanned):** ```json { "mode": "find_by_date", "date": "2026-07-01", "count": 100, "scanned": 2000, "next_page_token": 48752931, "range_complete": false } ``` ### Support For bugs, feature requests, or questions — reach us at https://docs.google.com/forms/d/e/1FAIpQLSfsKyzZ3nRED7mML47I4LAfNh\_mBwkuFMp1FgYYJ4AkDRgaRw/viewform?usp=dialog # Actor input Schema ## `category` (type: `string`): Which Hacker News list to pull stories from: Top, New, Best, Ask HN, Show HN, or Jobs. Only used when 'Date to scan' is left empty (Category mode). Ignored in Date mode. ## `date` (type: `string`): A single calendar day to scan, in YYYY-MM-DD format (e.g. 2026-07-01), based on UTC time. Filling this in switches the run to Date mode, which ignores 'Category' and instead scans every story, job posting, and poll from that day. Comments aren't returned as their own rows, but comment threads are still included on each item via 'Reply depth' below. Busy days can have more items than fit in one run — check 'range\_complete' in the output, and if it's false, use 'Page token' on a follow-up run to continue scanning the same day. ## `limit` (type: `integer`): The maximum number of stories or items to return in this run. Works the same way in both Category mode and Date mode. Default is 30, maximum is 200. ## `comment_limit` (type: `integer`): How many top-level comments to fetch and embed inside each story. Set to 0 to skip comments entirely and only get story details. Default is 10, maximum is 100. Only applies in Category mode — in Date mode, comment threading is controlled separately below. ## `reply_depth` (type: `integer`): How many levels of replies to fetch underneath each comment. 0 means top-level comments only, no replies (default and fastest). 1 adds direct replies, 2 adds another level below that, and so on. Works in both Category mode and Date mode. Higher values mean much longer run times on busy threads, so start low (1-2) unless you specifically need deep conversations. Maximum is 5. ## `replies_per_comment` (type: `integer`): The maximum number of replies to fetch at each level, per comment. Only matters if 'Reply depth' is above 0. For example, if a comment has 50 replies but this is set to 5, only the first 5 are fetched at that level. Default is 5, maximum is 20. ## `page_token` (type: `integer`): Used to continue a previous Date mode run that didn't finish scanning the full day (check 'range\_complete' in that run's output). Copy the 'next\_page\_token' value from that run's output here to pick up where it left off. Leave empty on your first run for a given day. Has no effect in Category mode. ## Actor input object example ```json { "category": "top", "limit": 30, "comment_limit": 10, "reply_depth": 5, "replies_per_comment": 5 } ``` # Actor output Schema ## `results` (type: `string`): The resolved stories (Get Stories) or matched items (Find by Date) for this run # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("onescales/hacker-news-data").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 = {} # Run the Actor and wait for it to finish run = client.actor("onescales/hacker-news-data").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 '{}' | apify call onescales/hacker-news-data --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=onescales/hacker-news-data", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Hacker News Data", "description": "Pull stories, comments, and other items from Hacker News in two flexible ways: browse the live front-page-style category lists (Top, New, Best, Ask, Show, Jobs), or scan every item posted within a specific date and time range. Optionally fetch nested comment threads several levels deep.", "version": "1.0", "x-build-id": "rqPqJejIMPxTTi0cv" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/onescales~hacker-news-data/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-onescales-hacker-news-data", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/onescales~hacker-news-data/runs": { "post": { "operationId": "runs-sync-onescales-hacker-news-data", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/onescales~hacker-news-data/run-sync": { "post": { "operationId": "run-sync-onescales-hacker-news-data", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "category": { "title": "Category [Category mode]", "enum": [ "top", "new", "best", "ask", "show", "job" ], "type": "string", "description": "Which Hacker News list to pull stories from: Top, New, Best, Ask HN, Show HN, or Jobs. Only used when 'Date to scan' is left empty (Category mode). Ignored in Date mode.", "default": "top" }, "date": { "title": "Date to scan [Date mode]", "type": "string", "description": "A single calendar day to scan, in YYYY-MM-DD format (e.g. 2026-07-01), based on UTC time. Filling this in switches the run to Date mode, which ignores 'Category' and instead scans every story, job posting, and poll from that day. Comments aren't returned as their own rows, but comment threads are still included on each item via 'Reply depth' below. Busy days can have more items than fit in one run — check 'range_complete' in the output, and if it's false, use 'Page token' on a follow-up run to continue scanning the same day." }, "limit": { "title": "Limit", "minimum": 1, "maximum": 200, "type": "integer", "description": "The maximum number of stories or items to return in this run. Works the same way in both Category mode and Date mode. Default is 30, maximum is 200.", "default": 30 }, "comment_limit": { "title": "Comments per story [Category mode]", "minimum": 0, "maximum": 100, "type": "integer", "description": "How many top-level comments to fetch and embed inside each story. Set to 0 to skip comments entirely and only get story details. Default is 10, maximum is 100. Only applies in Category mode — in Date mode, comment threading is controlled separately below.", "default": 10 }, "reply_depth": { "title": "Reply depth", "minimum": 0, "maximum": 5, "type": "integer", "description": "How many levels of replies to fetch underneath each comment. 0 means top-level comments only, no replies (default and fastest). 1 adds direct replies, 2 adds another level below that, and so on. Works in both Category mode and Date mode. Higher values mean much longer run times on busy threads, so start low (1-2) unless you specifically need deep conversations. Maximum is 5.", "default": 5 }, "replies_per_comment": { "title": "Replies per comment", "minimum": 1, "maximum": 20, "type": "integer", "description": "The maximum number of replies to fetch at each level, per comment. Only matters if 'Reply depth' is above 0. For example, if a comment has 50 replies but this is set to 5, only the first 5 are fetched at that level. Default is 5, maximum is 20.", "default": 5 }, "page_token": { "title": "Page token [Date mode]", "type": "integer", "description": "Used to continue a previous Date mode run that didn't finish scanning the full day (check 'range_complete' in that run's output). Copy the 'next_page_token' value from that run's output here to pick up where it left off. Leave empty on your first run for a given day. Has no effect in Category mode." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```