# Hacker News Search

Full-text search over Hacker News stories and comments through the Algolia HN Search API. Each result carries id, title, url, author, points, comment count, creation date, and the story or comment text with a plain-text variant for comments. Sort by relevance or date, and narrow with unix timestamp date bounds. Pagination is explicit and 1-based; has_more comes from the upstream page count. A query with no hits is a valid empty answer and is billed as one.

- **Documentation:** [https://scrappa.co/docs/hackernews-api/hackernews_search](https://scrappa.co/docs/hackernews-api/hackernews_search)
- **API group:** Hacker News API
- **Endpoint:** `GET https://scrappa.co/api/hackernews/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search query, e.g. dishwasher. |
| `type` | string | No | story or comment. Defaults to story. |
| `sort` | string | No | relevance or date. Defaults to relevance. |
| `page` | integer | No | 1-based page number. Defaults to 1. |
| `per_page` | integer | No | Results per page, 1-30. Defaults to 20. |
| `date_from` | integer | No | Only results created at or after this unix timestamp. |
| `date_to` | integer | No | Only results created at or before this unix timestamp. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/hackernews/search?query=dishwasher&type=story"
```

## Example response

```json
{
    "success": true,
    "data": {
        "results": [
            {
                "id": 43463200,
                "title": "I won't connect my dishwasher to your cloud",
                "url": "https://www.jeffgeerling.com/blog/2025/i-wont-connect-my-dishwasher-your-stupid-cloud",
                "author": "HieronymusBosch",
                "points": 1012,
                "num_comments": 663,
                "created_at": "2025-03-24T17:09:07Z"
            }
        ],
        "page": 1,
        "per_page": 20,
        "nb_hits": 199,
        "nb_pages": 100,
        "has_more": true
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 503 | Hacker News Upstream Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |
| 500 | Parser Drift | Hacker News returned a response shape this parser does not recognise. The incident has been reported; retrying will return the same result. |
| 422 | Bad Request Upstream | Hacker News rejected a value in this request. Never charged. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)