# Hacker News Search API. Stories matching your search.

Stories by keyword, ranked or newest first. We handle the proxies, blocks and platform changes.

[Get API key](https://socialtap.dev/signup/?next=%2Fplayground%2F%3Fendpoint%3Dhackernews.search_stories)

[In your agent: **Hacker News MCP server** →](https://socialtap.dev/mcp/hackernews/index.md)

## 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`

[Read the API reference](https://socialtap.dev/docs/reference/hackernews/search-stories/index.md)

- **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
- **`query`** is 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 socialtap`

`query = rust async`

[Open in playground](https://socialtap.dev/playground/?endpoint=hackernews.search_stories)

cURL:

```shell
curl -G 'https://socialtap.dev/v1/hackernews/search_stories' \
  --data-urlencode 'query=rust async' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

TypeScript SDK:

```typescript
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);
```

Node.js (fetch):

```javascript
const 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);
```

Python (requests):

```python
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"])
```

Go (net/http):

```go
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"])
}
```

200 OK:

```json
{
  "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": []
  }
}
```

Long arrays and strings are shortened here. Real responses are complete.

## One schema on 22 platforms.

The [response reference](https://socialtap.dev/docs/reference/hackernews/search-stories/index.md#response) lists every field, its type and when it is `null`. [See the full schema](https://socialtap.dev/resources/post/index.md).

- ### 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.

- **`platform`string**: Platform ID (tiktok, youtube, …).
- **`id`string**: Platform-native post ID (string; Instagram shortcode, Reddit with its t3_ prefix).
- **`url`string**: Canonical post URL.
- **`type`string**: Normalized content shape. New values may be added; treat unknown values as other.
- **`platform_type`string**: The platform's own product label, lowercase (reel, short, story, live, tweet, …).
- **`title`string**: Headline (YouTube title, Reddit title); null on caption-only platforms.
- **`text`string**: Caption, description or body as plain text.
- **`link_url`string**: 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.

[TikTok](https://socialtap.dev/apis/tiktok/index.md) · [Instagram](https://socialtap.dev/apis/instagram/index.md) · [Facebook](https://socialtap.dev/apis/facebook/index.md) · [YouTube](https://socialtap.dev/apis/youtube/index.md) · [Reddit](https://socialtap.dev/apis/reddit/index.md) · [Threads](https://socialtap.dev/apis/threads/index.md) · [GitHub](https://socialtap.dev/apis/github/index.md) · [LinkedIn](https://socialtap.dev/apis/linkedin/index.md) · [X](https://socialtap.dev/apis/x/index.md) · [Spotify](https://socialtap.dev/apis/spotify/index.md) · [Hacker News](https://socialtap.dev/apis/hackernews/index.md) · [Amazon](https://socialtap.dev/apis/amazon/index.md) · [Apple Music](https://socialtap.dev/apis/applemusic/index.md) · [Pinterest](https://socialtap.dev/apis/pinterest/index.md) · [Rumble](https://socialtap.dev/apis/rumble/index.md) · [Bluesky](https://socialtap.dev/apis/bluesky/index.md) · [Twitch](https://socialtap.dev/apis/twitch/index.md) · [Telegram](https://socialtap.dev/apis/telegram/index.md) · [TikTok Shop](https://socialtap.dev/apis/tiktokshop/index.md) · [Kwai](https://socialtap.dev/apis/kwai/index.md) · [Snapchat](https://socialtap.dev/apis/snapchat/index.md) · [SoundCloud](https://socialtap.dev/apis/soundcloud/index.md) · [Truth Social](https://socialtap.dev/apis/truthsocial/index.md) · [Kick](https://socialtap.dev/apis/kick/index.md) · [Komi](https://socialtap.dev/apis/komi/page/index.md) · [Lnk.Bio](https://socialtap.dev/apis/linkbio/profile/index.md) · [Linkme](https://socialtap.dev/apis/linkme/profile/index.md) · [Linktree](https://socialtap.dev/apis/linktree/profile/index.md) · [Pillar](https://socialtap.dev/apis/pillar/page/index.md) · [TikTok Ad Library](https://socialtap.dev/apis/tiktok-ad-library/index.md) · [Facebook Ad Library](https://socialtap.dev/apis/facebook-ad-library/index.md) · [Facebook Events](https://socialtap.dev/apis/facebook-events/index.md) · [Facebook Marketplace](https://socialtap.dev/apis/facebook-marketplace/index.md) · [Google Ads Transparency Center](https://socialtap.dev/apis/google-ads-transparency/index.md) · [LinkedIn Ad Library](https://socialtap.dev/apis/linkedin-ad-library/index.md)

## 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.

[Plans and packs](https://socialtap.dev/pricing/index.md) · [How this endpoint is priced](https://socialtap.dev/docs/reference/hackernews/search-stories/index.md#pricing) · [How credits work](https://socialtap.dev/docs/credits/index.md)

| 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](https://socialtap.dev/docs/reference/hackernews/search-stories/index.md).

**How do I find the Hacker News stories that link to my site?**

Send your domain as the query with search_in=url, for example query=example.com, and sort=newest to list them all, newest first.

**How much does the Hacker News Search API cost?**

A page of up to 100 stories costs 1 credit. Every successful page is charged, empty pages included. SocialTap credits cost $0.75–$1.97 per 1,000, depending on the plan or pack.

**How do I get the next page?**

Repeat the same request with cursor set to page.next_cursor from the previous response, keeping the other parameters. When page.has_more is false there are no more pages. Cursors expire after 24 hours.

Other platforms

## Posts on 21 more platforms.

- [TikTok Post API](https://socialtap.dev/apis/tiktok/post/index.md) (1 credit · `GET /v1/tiktok/post`)
- [Instagram Post API](https://socialtap.dev/apis/instagram/post/index.md) (1 credit · `GET /v1/instagram/post`)
- [Facebook Post API](https://socialtap.dev/apis/facebook/post/index.md) (1 credit · `GET /v1/facebook/post`)
- [YouTube Video API](https://socialtap.dev/apis/youtube/post/index.md) (1 credit · `GET /v1/youtube/post`)
- [Reddit Post API](https://socialtap.dev/apis/reddit/post/index.md) (1 credit · `GET /v1/reddit/post`)
- [Threads Post API](https://socialtap.dev/apis/threads/post/index.md) (1 credit · `GET /v1/threads/post`)
- [LinkedIn Post API](https://socialtap.dev/apis/linkedin/post/index.md) (1 credit · `GET /v1/linkedin/post`)
- [X (Twitter) Post API](https://socialtap.dev/apis/x/post/index.md) (1 credit · `GET /v1/x/post`)
- [Spotify Track API](https://socialtap.dev/apis/spotify/track/index.md) (1 credit · `GET /v1/spotify/track`)
- [Amazon Shop Posts API](https://socialtap.dev/apis/amazon/shop-posts/index.md) (1 credit / page · `GET /v1/amazon/shop_posts`)
- [Apple Music Track API](https://socialtap.dev/apis/applemusic/track/index.md) (1 credit · `GET /v1/applemusic/track`)
- [Pinterest Pin API](https://socialtap.dev/apis/pinterest/pin/index.md) (1 credit · `GET /v1/pinterest/pin`)
- [Rumble Video API](https://socialtap.dev/apis/rumble/post/index.md) (1 credit · `GET /v1/rumble/post`)
- [Bluesky Post API](https://socialtap.dev/apis/bluesky/post/index.md) (1 credit · `GET /v1/bluesky/post`)
- [Twitch Video and Clip API](https://socialtap.dev/apis/twitch/video/index.md) (1 credit · `GET /v1/twitch/video`)
- [Telegram Post API](https://socialtap.dev/apis/telegram/post/index.md) (1 credit · `GET /v1/telegram/post`)
- [Kwai Post API](https://socialtap.dev/apis/kwai/post/index.md) (1 credit · `GET /v1/kwai/post`)
- [Snapchat Spotlight API](https://socialtap.dev/apis/snapchat/spotlight/index.md) (1 credit · `GET /v1/snapchat/spotlight`)
- [SoundCloud Track API](https://socialtap.dev/apis/soundcloud/track/index.md) (1 credit · `GET /v1/soundcloud/track`)
- [Truth Social Post API](https://socialtap.dev/apis/truthsocial/post/index.md) (1 credit · `GET /v1/truthsocial/post`)
- [Kick Clip API](https://socialtap.dev/apis/kick/post/index.md) (1 credit · `GET /v1/kick/post`)

More Hacker News

## Hacker News API. 11 endpoints, one key.

- [Hacker News Story API](https://socialtap.dev/apis/hackernews/story/index.md) (1 credit · `GET /v1/hackernews/story`)
- [Hacker News Feed API](https://socialtap.dev/apis/hackernews/feed-stories/index.md) (1 credit / page · `GET /v1/hackernews/feed_stories`)
- [Hacker News User Stories API](https://socialtap.dev/apis/hackernews/user-stories/index.md) (1 credit / page · `GET /v1/hackernews/user_stories`)
- [Hacker News User Favorites API](https://socialtap.dev/apis/hackernews/user-favorites/index.md) (1 credit / page · `GET /v1/hackernews/user_favorites`)
- [Hacker News User API](https://socialtap.dev/apis/hackernews/user/index.md) (1 credit · `GET /v1/hackernews/user`)
- [Hacker News Comment API](https://socialtap.dev/apis/hackernews/comment/index.md) (1 credit · `GET /v1/hackernews/comment`)
- [Hacker News Comments API](https://socialtap.dev/apis/hackernews/comments/index.md) (1 credit / page · `GET /v1/hackernews/comments`)
- [Hacker News User Comments API](https://socialtap.dev/apis/hackernews/user-comments/index.md) (1 credit / page · `GET /v1/hackernews/user_comments`)
- [Hacker News Comment Search API](https://socialtap.dev/apis/hackernews/search-comments/index.md) (1 credit / page · `GET /v1/hackernews/search_comments`)
- [Hacker News Who Is Hiring API](https://socialtap.dev/apis/hackernews/whoishiring-jobs/index.md) (1 credit / page · `GET /v1/hackernews/whoishiring_jobs`)

## Try it with your own search.

Type it in the playground, or copy the request into your code.

100free credits

- No credit card
- Failed requests are free
- Works on all 276 endpoints

[Start for free](https://socialtap.dev/signup/) [Read the docs](https://socialtap.dev/docs/index.md)

---

[HTML version](https://socialtap.dev/apis/hackernews/search-stories/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)
