Hacker News Search API. Stories matching your search.
Stories by keyword, ranked or newest first. We handle the proxies, blocks and platform changes.
Hacker News Search API at a glance
Returns the public Hacker News stories that match your words, ranked by relevance or newest first: links, Ask HN, Show HN and Launch HN posts, jobs and polls. Filter by type, poster, points, comment count, date or the front page, or find who linked to a site. Each story has its title, the page it links to, its text as plain text, points and comment count, poster and posting time.
GET /v1/hackernews/search_stories
- 1 credit per page, $0.75–$1.97 per 1,000 pages
- 23 typed fields null when unknown
- 100 stories per page, HN Search's ranking: the best match of the words first, then the most points
queryis all it needs, e.g.rust async
Send one request. Get up to 100 stories back.
Copy the request in your language, or hand it to your agent. Sign up for an API key and your first 100 credits are free.
$ npm install socialtapquery = rust asyncconst params = new URLSearchParams({
query: "rust async",
});
const res = await fetch(`https://socialtap.dev/v1/hackernews/search_stories?${params}`, {
headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { data, page, meta } = body;
console.log(data, meta.credits_charged);import os
import requests
res = requests.get(
"https://socialtap.dev/v1/hackernews/search_stories",
params={"query": "rust async"},
headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data, page, meta = body["data"], body["page"], body["meta"]
print(data, meta["credits_charged"])require "json"
require "net/http"
uri = URI("https://socialtap.dev/v1/hackernews/search_stories")
uri.query = URI.encode_www_form('query' => 'rust async')
req = Net::HTTP::Get.new(uri)
req["x-api-key"] = ENV.fetch("SOCIALTAP_API_KEY")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
body = JSON.parse(res.body)
raise "#{body["error"]["code"]}: #{body["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
pp body["data"]
puts body["meta"]["credits_charged"]<?php
$query = http_build_query([
'query' => 'rust async',
]);
$ch = curl_init('https://socialtap.dev/v1/hackernews/search_stories?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['x-api-key: ' . getenv('SOCIALTAP_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) >= 400) {
throw new RuntimeException($body['error']['code'] . ': ' . $body['error']['message']);
}
print_r($body['data']);
echo $body['meta']['credits_charged'], PHP_EOL;package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
)
func main() {
q := url.Values{}
q.Set("query", "rust async")
req, err := http.NewRequest("GET", "https://socialtap.dev/v1/hackernews/search_stories?"+q.Encode(), nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body struct {
Data json.RawMessage `json:"data"`
Page json.RawMessage `json:"page"`
Meta map[string]any `json:"meta"`
Error *struct {
Code string `json:"code"`
Message string `json:"message"`
} `json:"error"`
}
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if body.Error != nil {
log.Fatalf("%s: %s", body.Error.Code, body.Error.Message)
}
fmt.Println(string(body.Data), body.Meta["credits_charged"])
}curl -G 'https://socialtap.dev/v1/hackernews/search_stories' \
--data-urlencode 'query=rust async' \
-H "x-api-key: $SOCIALTAP_API_KEY"{
"data": [
{
"approximate_fields": [],
"author": {
"avatar_url": null,
"display_name": null,
"id": "tazjin",
"is_verified": null,
"url": "https://news.ycombinator.com/user?id=tazjin",
"username": "tazjin"
},
"coauthors": [],
"duration_ms": null,
"hashtags": [],
"id": "26406989",
"is_nsfw": null,
"is_pinned": null,
"is_sponsored": null,
"language": null,
"link_url": "https://theta.eu.org/2021/03/08/async-rust-2.html",
"media": [],
"mentions": [],
"metrics": {
"comment_count": 482,
"like_count": 603,
"quote_count": null,
"repost_count": null,
"save_count": null,
"share_count": null,
"view_count": null
},
"platform": "hackernews",
"platform_specific": {
"hackernews": {
"poll_options": [],
"rank": null
}
},
"platform_type": "story",
"published_at": "2021-03-10T02:16:55Z",
"text": null,
"thumbnail_url": null,
"title": "Why asynchronous Rust doesn't work",
"type": "link",
"unknown_fields": [],
"url": "https://news.ycombinator.com/item?id=26406989"
},
{
"approximate_fields": [],
"author": {
"avatar_url": null,
"display_name": null,
"id": "bcantrill",
"is_verified": null,
"url": "https://news.ycombinator.com/user?id=bcantrill",
"username": "bcantrill"
},
"coauthors": [],
"duration_ms": null,
"hashtags": [],
"id": "45774086",
"is_nsfw": null,
"is_pinned": null,
"is_sponsored": null,
"language": null,
"link_url": "https://rfd.shared.oxide.computer/rfd/0609",
"media": [],
"mentions": [],
"metrics": {
"comment_count": 245,
"like_count": 449,
"quote_count": null,
"repost_count": null,
"save_count": null,
"share_count": null,
"view_count": null
},
"platform": "hackernews",
"platform_specific": {
"hackernews": {
"poll_options": [],
"rank": null
}
},
"platform_type": "story",
"published_at": "2025-10-31T16:49:26Z",
"text": "This RFD describes our distillation of a really gnarly issue that we hit in the Oxide control plane.[0] Not unlike our discovery of the async cancellation issue[1][2][3], this is larger than the issue itself -- and worse, the program that hits futurelock is correct from the prog…",
"thumbnail_url": null,
"title": "Futurelock: A subtle risk in async Rust",
"type": "link",
"unknown_fields": [],
"url": "https://news.ycombinator.com/item?id=45774086"
},
{
"approximate_fields": [],
"author": {
"avatar_url": null,
"display_name": null,
"id": "pjmlp",
"is_verified": null,
"url": "https://news.ycombinator.com/user?id=pjmlp",
"username": "pjmlp"
},
"coauthors": [],
"duration_ms": null,
"hashtags": [],
"id": "48019163",
"is_nsfw": null,
"is_pinned": null,
"is_sponsored": null,
"language": null,
"link_url": "https://tweedegolf.nl/en/blog/237/async-rust-never-left-the-mvp-state",
"media": [],
"mentions": [],
"metrics": {
"comment_count": 266,
"like_count": 446,
"quote_count": null,
"repost_count": null,
"save_count": null,
"share_count": null,
"view_count": null
},
"platform": "hackernews",
"platform_specific": {
"hackernews": {
"poll_options": [],
"rank": null
}
},
"platform_type": "story",
"published_at": "2026-05-05T07:26:03Z",
"text": null,
"thumbnail_url": null,
"title": "Async Rust never left the MVP state",
"type": "link",
"unknown_fields": [],
"url": "https://news.ycombinator.com/item?id=48019163"
}
],
"page": {
"has_more": true,
"next_cursor": "c1.EXAMPLE_CURSOR",
"next_cursor_expires_at": "2026-10-26T12:00:00Z",
"end_reason": null
},
"meta": {
"request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
"platform": "hackernews",
"source": "api",
"is_cached": false,
"credits_charged": 1,
"latency_ms": 1000,
"fetched_at": "2026-10-25T12:00:00Z",
"input": null,
"credits_remaining": 9999,
"client_request_id": null,
"warnings": []
}
}import { SocialTap } from "socialtap";
const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY
const res = await client.hackernews.searchStories.list({ query: "rust async" });
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
public class Main {
public static void main(String[] args) throws Exception {
String query = "query=" + encode("rust async");
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://socialtap.dev/v1/hackernews/search_stories?" + query))
.header("x-api-key", System.getenv("SOCIALTAP_API_KEY"))
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
// An error is {"error": {"code", "message", ...}}; success is {data, meta}, meta.credits_charged its price.
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());
}
static String encode(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8);
}
}using System.Text.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("SOCIALTAP_API_KEY"));
var query = string.Join("&",
"query=" + Uri.EscapeDataString("rust async"));
var res = await http.GetAsync("https://socialtap.dev/v1/hackernews/search_stories?" + query);
using var body = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
if (!res.IsSuccessStatusCode)
{
var error = body.RootElement.GetProperty("error");
throw new Exception($"{error.GetProperty("code")}: {error.GetProperty("message")}");
}
Console.WriteLine(body.RootElement.GetProperty("data"));
Console.WriteLine(body.RootElement.GetProperty("meta").GetProperty("credits_charged"));// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
use std::env;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let res = reqwest::blocking::Client::new()
.get("https://socialtap.dev/v1/hackernews/search_stories")
.query(&[("query", "rust async")])
.header("x-api-key", env::var("SOCIALTAP_API_KEY")?)
.send()?;
let ok = res.status().is_success();
let body: serde_json::Value = res.json()?;
if !ok {
return Err(format!("{}: {}", body["error"]["code"], body["error"]["message"]).into());
}
println!("{} {}", body["data"], body["meta"]["credits_charged"]);
Ok(())
}200 OK · GET https://socialtap.dev/v1/hackernews/search_storiesLong arrays and strings are shortened here. Real responses are complete.Docs One schema on 22 platforms.
The response reference lists every field, its type and when it is null. See the full schema.
Null means unknown
A field Hacker News doesn't show is null, never zero or an empty string, so a real zero always means zero.
What it accepts
Words to find stories by, as HN Search reads them: any word can match with a small typo, a phrase in quotes matches exactly, and a leading - leaves a word out (rust async, "memory safety" -rust).
Write one parser
Hacker News, TikTok, Instagram and 19 more platforms answer in these fields, so the code that reads one reads them all.
platformstring- Platform ID (tiktok, youtube, …).
idstring- Platform-native post ID (string; Instagram shortcode, Reddit with its t3_ prefix).
urlstring- Canonical post URL.
typestring- Normalized content shape. New values may be added; treat unknown values as other.
platform_typestring- The platform's own product label, lowercase (reel, short, story, live, tweet, …).
titlestring- Headline (YouTube title, Reddit title); null on caption-only platforms.
textstring- Caption, description or body as plain text.
link_urlstring- The page the post links to: a link post's target, a pin's destination, or the page its link card or link sticker opens; null when it links to none.
Live data from 35 platforms.
What teams build with the Hacker News Search API.
Find every Hacker News thread about your product
See who submitted links to your site
Collect Show HN launches in a category
Track a topic's stories over time
Find the most discussed stories on a subject
Good to know before you build.
- Results come from HN Search, the search Hacker News itself links to, which copies every story within minutes. Points and comment counts are as of its last update of the story: minutes behind for a story still being voted on, the final count for an older one.
- sort=relevance serves the first thousand matching stories, then ends with platform_limit. sort=newest walks back through every match.
- A poll lists its options by ID only: the Hacker News Story API returns their text and points.
- Stories Hacker News killed or that were deleted are not in the results.
- Words in Chinese, Japanese or Korean match only where they stand apart as words, so they find few stories.
1 credit per page. Failed requests are free.
Buy credits once and spend them on any endpoint, on any platform.
| Source | Price per successful page | Per 1,000 pages |
|---|---|---|
Platform API api | 1 credit | $0.75–$1.97 |
- Cache hits are free.
- Credits from packs and top-ups never expire.
- A monthly plan's credits are spent first, and what is left of them ends at each renewal.
- Prices exclude tax: sales tax is added at checkout where it applies.
- Outside the US, plans and packs are sold to businesses: checkout asks for your VAT, GST or other business tax ID.
Questions about the Hacker News Search API.
More in the API reference.
How do I find the Hacker News stories that link to my site?
How much does the Hacker News Search API cost?
How do I get the next page?
Try it with your own search.
Type it in the playground, or copy the request into your code.
- No credit card
- Failed requests are free
- Works on all 276 endpoints