# Hacker News API guide



## Start with Hacker News



Search Hacker News submissions or comments, resolve a selected story and retain the relationships in its available comment tree.



These requests use your API key and can spend credits. Check the current price on the endpoint page; each new page is a separate request. Later examples use illustrative identifiers: replace them with values from your earlier response.



### 1. Find stories



Keep id for the story lookup and hn_url for a discussion citation. url can point to an external article. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/hackernews/search)



**hackernews/search**

```
curl "https://www.monocrawl.com/v1/hackernews/search?query=developer%20tools&tags=story" \
  -H "x-api-key: mn_your_key_here"
```



### 2. Open the discussion



Replace the illustrative id with one returned by search. Preserve source text and timestamps. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/hackernews/story)



**hackernews/story**

```
curl "https://www.monocrawl.com/v1/hackernews/story?id=8863" \
  -H "x-api-key: mn_your_key_here"
```



### 3. Read the comment tree



Use the same story id. Keep parent_id and depth; inspect truncation and coverage. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/hackernews/story/comments)



**hackernews/story/comments**

```
curl "https://www.monocrawl.com/v1/hackernews/story/comments?id=8863" \
  -H "x-api-key: mn_your_key_here"
```



## Choose filters with the source behavior in mind



| Control | Behavior and limits |
| --- | --- |
| Search filters | tags selects story/comment and other supported kinds. numericFilters constrains numeric fields; created_at_i is Unix seconds, not milliseconds. Search page is zero-based. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/hackernews/search) |
| Discussion versus destination | hn_url identifies the discussion; url can be an external destination. Keep both for citations. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/hackernews/story) |
| Comment trees | The tree is flattened with parent IDs and depth under server bounds. Deleted nodes can be skipped while their visible replies remain. A tree response is not a cursor-paged search. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/hackernews/story/comments) |



Source availability, ordering and field coverage can change. Inspect warnings and partial-result metadata alongside the rows. See [runnable workflows](https://www.monocrawl.com/docs/workflows), [metric semantics](https://www.monocrawl.com/docs/metric-semantics), [computed fields](https://www.monocrawl.com/docs/computed-fields) and the [pagination matrix](https://www.monocrawl.com/docs/pagination).



## Match the operation to your task



| Your task | Endpoint | When to use it |
| --- | --- | --- |
| Search comment text | [`search`](https://www.monocrawl.com/docs/endpoints/hackernews/search) | Choose tags=comment instead of assuming story search covers comment bodies. |
| Read a user | [`profile`](https://www.monocrawl.com/docs/endpoints/hackernews/profile) | Use the declared username input, separate from numeric item IDs. |



Explore all documented operations by purpose below. Each endpoint reference contains its accepted parameters and current price.



### Accounts and audiences



- [`profile`](https://www.monocrawl.com/docs/endpoints/hackernews/profile)



### Search and discovery



- [`search`](https://www.monocrawl.com/docs/endpoints/hackernews/search)



### Posts and media



- [`story`](https://www.monocrawl.com/docs/endpoints/hackernews/story)



### Comments and replies



- [`story/comments`](https://www.monocrawl.com/docs/endpoints/hackernews/story/comments)



## Endpoint reference

## hackernews/profile

`GET /v1/hackernews/profile`

Karma, join date, about text and submission count for a Hacker News account, merged from the official Firebase API and the Algolia index.

*Hacker News profile*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | Hacker News username — e.g. `pg` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/hackernews/profile?handle=pg" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "about": "example",
  "created_at": "2026-09-01T12:00:00Z",
  "handle": "example",
  "id": "example",
  "karma": 0,
  "sources": [
    {
      "ok": false,
      "source": "example"
    }
  ],
  "submitted_count": 0,
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/hackernews/profile#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/hackernews/profile.json)


## hackernews/search

`GET /v1/hackernews/search`

Full-text search over Hacker News stories and comments with tag and numeric filters, via the Algolia HN index.

*Hacker News search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Full-text search query — e.g. `dropbox` |
| `tags` | no | Algolia tag filter: story, comment, poll, show_hn, ask_hn, front_page, author_USERNAME, story_ID. Comma-separated tags AND together; parentheses OR. — e.g. `story` |
| `numericFilters` | no | Comma-separated numeric conditions on points, num_comments or created_at_i — e.g. `points>100` |
| `hitsPerPage` | no | Results per page, 1-100 (default 25) — e.g. `25` |
| `page` | no | Zero-based page number — e.g. `0` |
| `cursor` | no | Pagination cursor from a previous response; equivalent to page — e.g. `1` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/hackernews/search?query=dropbox" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "12345",
      "type": "story",
      "title": "Example story",
      "points": 42
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/hackernews/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/hackernews/search.json)


## hackernews/story

`GET /v1/hackernews/story`

A Hacker News story with score, author, text and an exact comment count in one call.

*Hacker News story*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Numeric Hacker News item id — e.g. `8863` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/hackernews/story?id=8863" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "12345",
  "title": "Example story",
  "hn_url": "https://news.ycombinator.com/item?id=12345",
  "points": 42
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/hackernews/story#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/hackernews/story.json)


## hackernews/story/comments

`GET /v1/hackernews/story/comments`

The full comment tree of a Hacker News story in one call, flattened with depth and parent ids (up to 500 comments).

*Hacker News story comments*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Numeric Hacker News story id — e.g. `8863` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/hackernews/story/comments?id=8863" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "12346",
      "parent_id": "12345",
      "text": "Illustrative comment",
      "depth": 0
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/hackernews/story/comments#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/hackernews/story/comments.json)