{ "openapi": "3.0.1", "info": { "title": "HackerNews Insights Scraper — Stories, Comments & Velocity", "description": "Hacker News stories, full comment trees, user karma and contact info, story velocity tracking, history deltas. Search all 3.7M stories with filters for points, karma, domain, dates, keywords. For VCs hunting Show HN, recruiters mining talent, journalists tracking tech, and AI/RAG pipelines.", "version": "1.0", "x-build-id": "drdCrEWn8lykNR9tf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/brilliant_gum~hackernews-insights-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-brilliant_gum-hackernews-insights-scraper", "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/brilliant_gum~hackernews-insights-scraper/runs": { "post": { "operationId": "runs-sync-brilliant_gum-hackernews-insights-scraper", "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/brilliant_gum~hackernews-insights-scraper/run-sync": { "post": { "operationId": "run-sync-brilliant_gum-hackernews-insights-scraper", "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": { "lists": { "title": "Live lists", "uniqueItems": true, "type": "array", "description": "Built-in HN front-page lists. 'top' = top stories, 'best' = highest rated this period, 'new' = newest, 'ask' = Ask HN, 'show' = Show HN, 'job' = job posts.", "items": { "type": "string", "enum": [ "top", "best", "new", "ask", "show", "job" ], "enumTitles": [ "Top stories (top)", "Best stories (best)", "New stories (new)", "Ask HN (ask)", "Show HN (show)", "Job posts (job)" ] }, "default": [] }, "queries": { "title": "Search queries", "type": "array", "description": "Full-text search over Hacker News history via Algolia. Each query returns up to maxStoriesPerQuery matches. Searches across 3.7M stories from 2007 onwards.", "default": [], "items": { "type": "string" } }, "tags": { "title": "Algolia tag filter", "uniqueItems": true, "type": "array", "description": "Restrict search results to specific HN tags. Only applied when 'queries' is non-empty or 'algoliaTagsOnly' is true.", "items": { "type": "string", "enum": [ "story", "comment", "poll", "pollopt", "show_hn", "ask_hn", "front_page", "job" ], "enumTitles": [ "Story", "Comment", "Poll", "Poll option", "Show HN", "Ask HN", "Made the front page", "Job" ] }, "default": [] }, "tagSearchOnly": { "title": "Search by tags only (no query needed)", "type": "boolean", "description": "When checked, the scraper runs a tag-only search using the 'tags' field above — useful for fetching, say, 'all Show HN posts with > 100 points'. No 'queries' needed.", "default": false }, "storyIds": { "title": "Story IDs", "type": "array", "description": "Direct Hacker News story IDs to fetch (https://news.ycombinator.com/item?id=XXX).", "default": [], "items": { "type": "string" } }, "userIds": { "title": "User IDs", "type": "array", "description": "Hacker News usernames to enrich (returns karma, about, contact info, dominant topics, submission velocity).", "default": [], "items": { "type": "string" } }, "minPoints": { "title": "Minimum points (score)", "minimum": 0, "type": "integer", "description": "Skip stories below this score. 0 = no filter.", "default": 0 }, "minComments": { "title": "Minimum comments", "minimum": 0, "type": "integer", "description": "Skip stories with fewer comments than this. 0 = no filter.", "default": 0 }, "minAuthorKarma": { "title": "Minimum author karma", "minimum": 0, "type": "integer", "description": "Skip stories whose author karma is below this. Requires extra user lookups (slower).", "default": 0 }, "dateFrom": { "title": "From date (ISO YYYY-MM-DD)", "type": "string", "description": "Only include stories submitted on/after this date.", "default": "" }, "dateTo": { "title": "To date (ISO YYYY-MM-DD)", "type": "string", "description": "Only include stories submitted on/before this date.", "default": "" }, "keywords": { "title": "Keywords (any-match, OR)", "type": "array", "description": "Filter stories whose title contains ANY of these keywords (case-insensitive). Applied after fetch.", "default": [], "items": { "type": "string" } }, "domains": { "title": "URL domains filter", "type": "array", "description": "Only keep stories whose URL domain matches one of these (e.g. 'arxiv.org', 'github.com'). Self-posts (Ask HN, Show HN text) skipped when this is set.", "default": [], "items": { "type": "string" } }, "includeComments": { "title": "Include full comment trees", "type": "boolean", "description": "Fetch every comment under each story (charged per comment). Off by default to keep costs predictable.", "default": false }, "commentDepth": { "title": "Max comment depth", "minimum": 1, "maximum": 10, "type": "integer", "description": "Limit recursion depth for comment trees. 1 = top-level only, 3 = top + 2 reply tiers.", "default": 3 }, "maxCommentsPerStory": { "title": "Max comments per story", "minimum": 0, "type": "integer", "description": "Hard cap on the number of comments fetched per story (after depth filter). Protects cost on viral threads.", "default": 200 }, "includeAuthorProfiles": { "title": "Enrich with author profiles", "type": "boolean", "description": "Add a user record per story author (karma, about, contact info, dominant topics).", "default": false }, "maxStoriesPerList": { "title": "Max stories per list", "minimum": 1, "maximum": 500, "type": "integer", "description": "Cap stories taken from each live list (top/best/new/ask/show/job).", "default": 30 }, "maxStoriesPerQuery": { "title": "Max stories per query", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap stories returned per Algolia search query.", "default": 50 }, "sortBy": { "title": "Algolia sort", "enum": [ "popularity", "date" ], "type": "string", "description": "Algolia search ranking. 'popularity' = highest engagement first. 'date' = newest first.", "default": "popularity" }, "includeAnalytics": { "title": "Compute story analytics", "type": "boolean", "description": "Add per-story velocity (pointsPerHour, commentsPerHour), comment tree depth, top commenters, domain stats.", "default": true }, "includeContactInfo": { "title": "Extract user contact info", "type": "boolean", "description": "Scan user.about for emails, Twitter/X handles, GitHub, LinkedIn, websites. Applied to author profiles and userIds.", "default": true }, "enableHistory": { "title": "Track score/comment growth across runs", "type": "boolean", "description": "Persist a per-story snapshot of score and comment count between runs. Each story output then includes 'history.delta' (scoreDelta, commentsDelta, scorePerHour, isNew). Stored in the 'hackernews-history' KV store.", "default": false }, "historyStoreName": { "title": "History KV store name", "type": "string", "description": "Named key-value store for history snapshots.", "default": "hackernews-history" }, "maxConcurrency": { "title": "Concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum parallel fetches (item + comment lookups).", "default": 6 }, "minDelayMs": { "title": "Per-request throttle (ms)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Floor delay between requests per worker. Firebase tolerates very high rates; default is conservative.", "default": 30 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional. Proxies are included and configured automatically — leave this empty." } } }, "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 } } } } } } } } } }