# hackernews.news.search

Hacker News stories by query, ranked by relevance

> Search Hacker News stories and comments

Page: https://telipot.com/catalog/tasks/hackernews.news.search · Markdown: https://telipot.com/catalog/tasks/hackernews.news.search/md · JSON: https://telipot.com/catalog/tasks/hackernews.news.search/json

| Field | Value |
| --- | --- |
| provider | [Hacker News](https://telipot.com/catalog/providers/hackernews) `hackernews` |
| capability | [`news.search`](https://telipot.com/catalog/capabilities/news.search) |
| kind | data |
| tier | core |
| price | Free (Free · no account needed) |
| identity | No account |
| auth | `public · no credential` |
| scope | public |
| principal | none |
| required_scopes | none |
| retention | standard |
| route | `GET https://hn.algolia.com/api/v1/search` |
| verification | Verified on 2026-10-05. We ran a real request and checked the answer. This is a spot check, not a success rate. |
| status | live |
| docs | https://hn.algolia.com/api |

## Preview the price · nothing runs

```bash
telipot run hackernews.news.search \
  --input-json '{"query":"agent tools","hitsPerPage":2}' \
  --quote
```

## Run it

```bash
telipot run hackernews.news.search \
  --input-json '{"query":"agent tools","hitsPerPage":2}'
```

```bash
curl https://api.telipot.com/v1/tasks/hackernews.news.search/run \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"agent tools","hitsPerPage":2}'
```

## Input

| Field | In | Type | Required | Constraints | Note |
| --- | --- | --- | --- | --- | --- |
| `query` | queryParams | string | yes |  |  |
| `tags` | queryParams | string | no | one of "story", "comment"; default "story" |  |
| `hitsPerPage` | queryParams | integer | no | 1 to 50; default 10 |  |

## Input schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "examples": [
        "agent tools"
      ]
    },
    "tags": {
      "type": "string",
      "enum": [
        "story",
        "comment"
      ],
      "default": "story"
    },
    "hitsPerPage": {
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

## Output schema

```json
{
  "type": "object",
  "required": [
    "hits",
    "hitsPerPage",
    "nbHits",
    "nbPages",
    "page",
    "query"
  ],
  "properties": {
    "hits": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "objectID",
          "author",
          "created_at",
          "created_at_i",
          "_tags"
        ],
        "properties": {
          "objectID": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "points": {
            "type": [
              "integer",
              "null"
            ]
          },
          "num_comments": {
            "type": [
              "integer",
              "null"
            ]
          },
          "story_id": {
            "type": "integer"
          },
          "story_text": {
            "type": "string"
          },
          "comment_text": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "created_at_i": {
            "type": "integer"
          },
          "updated_at": {
            "type": "string"
          },
          "_tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "hitsPerPage": {
      "type": "integer"
    },
    "nbHits": {
      "type": "integer"
    },
    "nbPages": {
      "type": "integer"
    },
    "page": {
      "type": "integer"
    },
    "params": {
      "type": "string"
    },
    "processingTimeMS": {
      "type": "integer"
    },
    "query": {
      "type": "string"
    }
  }
}
```

## Example response

From `examples/hackernews.news.search.json`.

```json
{
  "hits": [
    {
      "_tags": [
        "story",
        "author_user"
      ],
      "author": "user",
      "created_at": "2026-07-09T15:45:17Z",
      "created_at_i": 1783611917,
      "num_comments": 40,
      "objectID": "48847834",
      "points": 96,
      "story_id": 48847834,
      "story_text": "Hey HN! We built a browser-based agent that runs inside an authenticated web app, watches how the app calls its own APIs, and automatically turns those into agent tools. You can think of it as an auto…",
      "title": "Show HN: Reverse-engineering web apps into agent tools",
      "updated_at": "2026-07-20T14:39:08Z"
    },
    {
      "_tags": [
        "story",
        "author_user"
      ],
      "author": "user",
      "created_at": "2026-03-24T06:31:15Z",
      "created_at_i": 1774333875,
      "num_comments": 8,
      "objectID": "47499242",
      "points": 50,
      "story_id": 47499242,
      "title": "Fast regex search: indexing text for agent tools",
      "updated_at": "2026-04-09T02:11:45Z",
      "url": "https://cursor.com/blog/fast-regex-search"
    }
  ],
  "hitsPerPage": 2,
  "nbHits": 69733,
  "nbPages": 500,
  "page": 0,
  "params": "query=agent+tools&hitsPerPage=2&advancedSyntax=true&analyticsTags=backend",
  "processingTimeMS": 36,
  "query": "agent tools"
}
```