archive/trends — the history of a niche, grouped by item

This is archive data, and that is the point. A live platform API can tell you what is happening now. It cannot tell you what was happening last Tuesday, because it does not keep a record. We wrote down every hour, which is why this endpoint can answer a question about the past at all.

The call

Parameters (4)

That list is the whole list, and anything else is ignored in silence. An undeclared parameter is not rejected — it produces no error, no warning and no filtering. Check a parameter against this table before assuming a narrower result came back.

What the parameter list does not tell you

This is the endpoint that cannot be replicated by calling a platform API. Hacker News will tell you its front page right now; it will not tell you its front page on 18 September, because it does not keep one. We wrote down every hour, so the question 'what was happening then' has an answer here and nowhere upstream.

GROUPED BY ITEM, NOT BY WINDOW, and that shape is the whole design. A window is how the archive stores — one row per item per hour. An item carrying its own series is how the question gets asked: you want the trajectory of a thing, not a stack of unrelated snapshots. The regrouping happens in the database so you never have to stitch windows together yourself.

`movement` on each item is oldest position minus newest, and positive means it climbed. Read it together with `points` in the series, never alone: a change of position with no change in points is a tie reshuffle, not a trend, and ties are the rule rather than the exception in these rankings.

`left_at` is null while an item is still in the ranking. That null is not a missing value — it is the item not having left yet, which is a fact, and the reason the field is not an empty string or a zero date.

Measured caveats (3)

Real responses

Captured, not composed. 1 response we could actually make from this machine:

$ curl "https://honesthook.com/api/v1/trends/ai-agents?hours=168"
{"error":"chave_ausente"}

HTTP 401

Why there is no success body on this page

The 200 body for this endpoint is not transcribed here. Reading it needs a client key, and there is no client key on the machine these pages were built from — internal keys exist only as hashes, by design. An example we never received would look exactly like one we did, so instead of composing one, the response shape is documented field by field on the schema pages below. Those are generated from the contract and tested against it in both directions; an invented example would be tested by nothing.

Response shapes (3)

• Item — What `archive/trends` returns: an item, when it entered the ranking, when it left, its best position, and the full series of hourly readings behind it.
• SeriesPoint — A single reading in an item's series: where it sat, how many points it had, how many comments. The archive keeps one of these per item per hour and never deletes them.
• ApiError — Every 4xx and 5xx from the API carries this object. The `error` value is a stable string you can branch on; the extra fields appear only for the errors that have something to report.

Error codes (8)

Every one of them carries the same body shape: ApiError. The error value is a stable string you can branch on — branch on that, never on the message text.

400 · 401 · 402 · 404 · 405 · 451 · 503 · 502

Machine-readable

This endpoint is in /openapi.json (OpenAPI 3.1), with its cost on the operation itself. If you are generating a client, use the spec rather than this page — and note that the spec is filtered by what is switched on right now, so it is the better answer to "can I call this today".