# Hacker News API: Search stories > Searches Hacker News stories or comments by words, date range and sort order. Comments include their parent story's website link when one exists; text-only stories have no website link. Unofficial. Not affiliated with or endorsed by Hacker News. - Page: https://fous.com/methods/news.ycombinator.com/search-stories - Method: `news.ycombinator.com/search_stories`, version 1 - Website: news.ycombinator.com - Returns: title, comment text, author, points, comment count, posted date, website link, Hacker News link, item ID - Effect: read (it gets data and changes nothing) - Sign-in: none needed - Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free - Verified: Nov 2, 2026 ## Inputs | Field | Type | Required | In the run below | Description | |---|---|---|---|---| | `page` | integer | no | | Page number, starting with 1, such as 2. Default 1. | | `sort` | string | no | | Order by relevance or newest, such as newest. One of "relevance", "newest". Default "relevance". | | `type` | string | no | | Search stories or comments, such as comments. One of "stories", "comments". Default "stories". | | `query` | string | yes | `"remote work"` | Words to search for, such as remote work. | | `max_results` | integer | no | | Maximum results on this page, such as 20. Default 20. | | `time_window` | string | no | | How far back to search, such as past_week. One of "past_day", "past_week", "past_month", "past_year", "all_time". Default "all_time". | ## Output From a run on Oct 23, 2026, shortened. Its input: ```json { "query": "remote work" } ``` Its output: ```json { "results": [ { "title": "Remote work doesn't seem to affect productivity, Fed study finds", "author": "simula67", "points": 848, "item_id": "39037589", "posted_at": "2024-01-18T03:55:56Z", "website_url": "https://www.bloomberg.com/news/articles/2024-01-16/remote-work-doesn-t-seem-to-affect-productivity-fed-study-finds", "comment_text": null, "comment_count": 579, "hacker_news_url": "https://news.ycombinator.com/item?id=39037589" }, { "title": "Written communication is remote work super power", "author": "snird", "points": 831, "item_id": "23577228", "posted_at": "2020-06-19T18:08:45Z", "website_url": "https://snir.dev/blog/remote-async-communication/", "comment_text": null, "comment_count": 190, "hacker_news_url": "https://news.ycombinator.com/item?id=23577228" }, { "title": "SSH hacks – a little sanity for remote workers", "author": "mxfurman", "points": 770, "item_id": "23025756", "posted_at": "2020-04-29T23:20:48Z", "website_url": "https://smallstep.com/blog/ssh-tricks-and-tips/", "comment_text": null, "comment_count": 227, "hacker_news_url": "https://news.ycombinator.com/item?id=23025756" } ] } ``` ## Run it From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output: ```bash curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"news.ycombinator.com/search_stories","input":{"query":"remote work"}}' ``` From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`. ## Ask your agent - Find Hacker News stories about rust borrow checker posted in the past week, sorted by newest - Show me the top comments discussing remote work from the past month on Hacker News - Search HN for stories mentioning sqlite performance, all time, relevance order, 50 results - Look up recent comments on ycombinator.com about LLM fine-tuning from the past day, newest first - Get page 2 of Hacker News stories matching kubernetes networking from the past year ## Input schema ```json { "type": "object", "required": [ "query" ], "properties": { "page": { "type": "integer", "default": 1, "minimum": 1, "description": "Page number, starting with 1, such as 2." }, "sort": { "enum": [ "relevance", "newest" ], "type": "string", "default": "relevance", "description": "Order by relevance or newest, such as newest." }, "type": { "enum": [ "stories", "comments" ], "type": "string", "default": "stories", "description": "Search stories or comments, such as comments." }, "query": { "type": "string", "minLength": 1, "description": "Words to search for, such as remote work." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "description": "Maximum results on this page, such as 20." }, "time_window": { "enum": [ "past_day", "past_week", "past_month", "past_year", "all_time" ], "type": "string", "default": "all_time", "description": "How far back to search, such as past_week." } } } ``` ## Output schema ```json { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "title", "comment_text", "author", "points", "comment_count", "posted_at", "website_url", "hacker_news_url", "item_id" ], "properties": { "title": { "type": [ "string", "null" ], "description": "Story title." }, "author": { "type": [ "string", "null" ], "description": "Hacker News author." }, "points": { "type": [ "integer", "null" ], "description": "Story points, when available." }, "item_id": { "type": "string", "description": "Hacker News item ID." }, "posted_at": { "type": [ "string", "null" ], "description": "Posted date and time in UTC, ISO 8601." }, "website_url": { "type": [ "string", "null" ], "description": "Story website link, or null for a text-only story." }, "comment_text": { "type": [ "string", "null" ], "description": "Comment in plain text; null for stories." }, "comment_count": { "type": [ "integer", "null" ], "description": "Number of story comments; null for comments." }, "hacker_news_url": { "type": "string", "description": "Link to the item on Hacker News." } }, "additionalProperties": false }, "description": "Stories or comments matching the search." } } } ``` ## See more - [Hacker News API: Get discussion](https://fous.com/methods/news.ycombinator.com/get-discussion.md): Gets a Hacker News story and its comments in the order shown on the site. The story can be given as a discussion link or as words from its title. Deleted and flagged comments are left out. - [Hacker News API: List stories](https://fous.com/methods/news.ycombinator.com/list-front-page.md): Lists current Hacker News stories in rank order from the top, newest, best, Ask HN, Show HN or jobs list. - [Hacker News API: Search YC companies](https://fous.com/methods/ycombinator.com/search-companies.md): Searches the Y Combinator company directory by keyword, industry, batch, location, hiring and status, returning companies in directory order. - [Hacker News API: List Who is hiring posts](https://fous.com/methods/news.ycombinator.com/list-hiring-posts.md): Lists top-level job posts from a monthly Ask HN: Who is hiring? thread in thread order, with post text and the company, roles, location, work arrangement, salary and application contact inferred from each post. - [Hacker News API: Get YC company profile](https://fous.com/methods/ycombinator.com/get-company.md): Looks up a Y Combinator company by name or YC company page link and returns its profile, founders, social links and open job count. - [Reddit API: Search posts](https://fous.com/methods/reddit.com/search-posts.md): Finds public Reddit posts by topic, optionally in one community, for a time window and sort order. Returns up to 100 posts in Reddit search order with score, comment count, text and link. - [Yahoo API: Search Yahoo News](https://fous.com/methods/yahoo.com/search-news.md): Searches Yahoo News articles by keyword, newest first or by relevance, with optional publication dates and pages; returns only articles hosted on Yahoo News, with authors, original publisher and section. - [TechCrunch API: Search articles](https://fous.com/methods/techcrunch.com/search-news.md): Searches TechCrunch articles by keyword, with an optional publication date range and newest or most relevant order. - [All Hacker News methods](https://fous.com/methods/ycombinator.com.md)