> For the complete documentation index, see [llms.txt](https://agpt.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agpt.co/docs/integrations/block-integrations/search-4.md). # Hacker News Search Search Hacker News stories and comments through HN Search (hn.algolia.com), the public search API that Algolia runs for Hacker News. It needs no account or API key. HN Search allows 10,000 requests an hour from one IP address, and every agent running on the same server shares that allowance. ## Hacker News Search ### What it is Search Hacker News stories and comments by keyword, author, date, points or linked domain, sorted by relevance or newest first. Use it to find mentions of a product, links to a website, or the most upvoted stories of the week. Uses HN Search by Algolia, which needs no account. exact\_match is on by default, so words that are only spelled alike are left out; turn it off to also catch misspellings. ### How it works Calls HN Search's `search` endpoint, or `search_by_date` when `sort_by` is newest, and gets up to 1,000 results in one request. Relevance puts the best matches first, then the stories with the most points, then the most comments. With an empty query everything matches equally, so relevance sorts by points. `search_for` becomes HN Search's `tags` filter (`story`, `comment`, `(story,comment)`, `show_hn`, `ask_hn` or `front_page`), plus `author_` when `author` is set. The time inputs and the minimums become `numericFilters` on `created_at_i`, `points` and `num_comments`. Only stories have points and comment counts, so a minimum above 0 leaves comments out. `match_in` limits matching to a story's `title` or `url`. Comments have neither, so the block refuses that combination instead of returning nothing. HN Search allows typos unless told not to. Then `autogpt` also matches `automotive` and `automation`, hundreds of thousands of comments instead of a few hundred, and sorted newest first those near misses take over. So `exact_match` is on by default and turns typo tolerance off. Plurals still match, and the last word still matches the start of longer words (`agent` finds `agents` and `agentic`). Turn `exact_match` off to also catch misspellings. Quotes around a phrase and a `-` before a word work too. `total_matches` is HN Search's count of every match, even past the 1,000 it returns. Text comes back as plain text: paragraphs become blank lines, italics become `*asterisks*`, code keeps its indentation, and links show their full URL. HN Search adds new stories and comments a minute or two after they are posted. Times are in UTC. ### Inputs | Input | Description | Type | Required | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------- | | query | Words to search for. Put a phrase in double quotes to match it as a phrase, and put - before a word to leave out items that have it. Leave empty to match everything, e.g. for the top stories of the past week. | str | No | | search\_for | What to search: stories, comments, stories\_and\_comments, show\_hn or ask\_hn posts, or front\_page (only the stories on the front page now) | "stories" \| "comments" \| "stories\_and\_comments" \| "show\_hn" \| "ask\_hn" \| "front\_page" | No | | match\_in | Where the query must match: anywhere (title, link, text and author), title, or url (the link a story points to, e.g. to find links to a domain). title and url only match stories. | "anywhere" \| "title" \| "url" | No | | exact\_match | Match the query words as written, without typo tolerance. On by default, because typo tolerance makes 'autogpt' also match 'automotive' and 'automation'. Plurals still match. Turn it off to also catch misspellings. | bool | No | | sort\_by | relevance: best matches first, then most points, then most comments. newest: newest first. | "relevance" \| "newest" | No | | created\_after | Only items posted at or after this time: an ISO 8601 date or time (2026-09-01, 2026-09-01T12:00:00Z; UTC unless it has an offset), or an age such as 24h, 7d or 2w | str | No | | created\_before | Only items posted before this time, written the same way as created\_after | str | No | | author | Only items posted by this Hacker News username (case-sensitive) | str | No | | min\_points | Only stories with at least this many points. Comments have no points, so any value above 0 leaves comments out. | int | No | | min\_comments | Only stories with at least this many comments. Any value above 0 leaves comments out. | int | No | | max\_results | Most results to return (up to 1,000) | int | No | ### Outputs | Output | Description | Type | | -------------- | ---------------------------------------------------------------------------------------------------- | --------------------- | | error | Error message if the operation failed | str | | results | Matching stories and comments, in the chosen order | List\[HackerNewsItem] | | result | Each matching story or comment | HackerNewsItem | | total\_matches | How many items match in all. Can be more than the results returned: HN Search returns at most 1,000. | int | ### Possible use case **Brand Monitoring**: Every morning, search stories and comments from the past day for your product's name, newest first, and post new mentions to Slack. **Who Links to Us**: Set `match_in` to `url` and search for your domain to find every story that links to your site, with its points and comment count. **Weekly Digest**: Leave the query empty, set `created_after` to `7d` and sort by relevance to get the most upvoted stories of the week. *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://agpt.co/docs/integrations/block-integrations/search-4.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.