# Hacker News Stories

Returns one page of stories from a Hacker News list: top, new, best, ask, show or jobs. Each story carries its id, title, url, score, author, ISO 8601 creation time, descendant count, kid ids, type and optional text. Fields Hacker News does not provide are omitted. Pagination is explicit: pages are never fetched for you, so one request performs exactly one list lookup plus the item lookups for the requested page. A page past the end of the list is a valid empty answer.

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

## 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 |
| --- | --- | --- | --- |
| `type` | string | No | Story list: top, new, best, ask, show or jobs. Defaults to top. |
| `page` | integer | No | 1-based page number. Defaults to 1. |
| `per_page` | integer | No | Stories per page, 1-30. Defaults to 20. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/hackernews/stories?type=top&page=1&per_page=20"
```

## Example response

```json
{
    "success": true,
    "data": {
        "stories": [
            {
                "id": 50068437,
                "title": "DishwasherBench \u2013 Can Frontier Models Stack a Dishwasher?",
                "url": "https://github.com.composo-ai/DishwasherBench",
                "score": 62,
                "by": "mlukewizard",
                "created_at": "2026-10-13T08:24:06Z",
                "descendants": 30,
                "kids": [
                    50068920,
                    50068438,
                    50070342,
                    50069632,
                    50069250
                ],
                "type": "story"
            }
        ],
        "page": 1,
        "per_page": 20,
        "total": 500,
        "has_more": true
    },
    "meta": {
        "endpoint_family": "stories",
        "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. |

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