Costs 10 credits, and CHARGES ONLY IF IT FINDS MOVEMENT. An empty result is a 200 with credits_charged: 0 and a note saying so, not an error and not a charge: the risk of an empty window sits with us, so you do not need defensive logic to avoid calling.

RANKED BY POINTS GAINED, NOT BY POSITION. This is the caveat that matters most, so it is stated before the parameters. Measured on 2026-09-06 across 19 pairs of windows: position changed for 19 of 29 items WITHOUT A SINGLE POINT CHANGING. Most items in a snapshot sit within a few points of each other, so ties are the rule, and a tie reshuffle looks exactly like movement if you read position. points_gained is Hacker News's own counter, not a number we derive, and it is what this endpoint sorts by.

interval_min IS THE REAL ELAPSED TIME between the two captures compared, not the window you asked for. The endpoint picks the archived window whose real capture time is closest to hours ago — windows are not equidistant, and observed intervals have ranged from 12 to 321 minutes. Asking hours=24 against an archive that is 20 hours deep returns interval_min: 1208, not 1440. Divide by this number, not by the one you sent.

An unknown niche is NOT a 404 here: it produces the same empty, uncharged 200 as a quiet window. Confirm the niche exists at /api/v1/nichos before reading an empty result as 'nothing moved'.

{
  "niche": "ai-agents",
  "interval_min": 1208,
  "note": "nothing gained traction in this window -- not charged",
  "items": [
    {
      "external_id": "49569136"
    }
  ]
}