Home · Docs · Recipes · What was trending the day a competitor launched
What was trending the day a competitor launched
Point `from` and `to` at one past day and read back the ranking as the archive recorded it. This is the question no live API can answer.
4 steps, using 2 endpoints. Step 1 is free and needs no key.
Read these first — they cost money if you do not
3 measured caveats apply to this recipe. They are worth more than the steps below: each one is a way the API answers plausibly while meaning something other than what you assumed.
A nonexistent niche is not a 404 — and it spends the call
Nothing validates the niche name. A typo returns `items: []` with `points: 0` and HTTP 200, AND still spends a call, because the quota counter increments before the archive is read. An empty answer therefore means one of two different things — the niche is quiet, or the niche does not exist — and the response does not distinguish them. This is why step 1 of every recipe here resolves names at `/api/v1/nichos` first: that endpoint is free and needs no key, so the check costs nothing.
Source: The `/api/v1/trends/{niche}` description in the served `/openapi.json`.
An unknown parameter is ignored in silence
`/trends` declares exactly four inputs: `niche`, `from`, `to` and `limit`. Anything else is not rejected — it is ignored. A `?platform=hackernews` produces no error, no warning and no filtering: you get the unfiltered answer and nothing tells you the filter did not apply. Check the parameter against the list before assuming a narrower result.
Source: The declared parameter list in `lib/rotas-da-api.js` and the published `/openapi.json`.
The series is capped, and says when it was cut
`/trends` is capped at 5000 series points and a 90-day span, both enforced in the database. When a cap is hit, `truncated` is true and the series is incomplete — narrow the interval rather than drawing conclusions from a partial series. `limit` is a hint only: the hard cap lives in the database and a larger value does not raise it.
Source: The `/api/v1/trends/{niche}` description in the served `/openapi.json`.
The 4 steps
1. Resolve the niche name first — it is free, and skipping it costs
Nothing validates a niche name downstream, so a typo answers 200 with an empty list and still spends a call. This endpoint needs no key and costs no credits, so there is never a reason to guess. Take the `id` values from the response and use those verbatim.
$ curl -s "https://honesthook.com/api/v1/nichos"
{"niches":[{"id":"ai-agents","label":"AI agents","windows_24h":24,"last_window":"2026-10-02T09:00:00+00:00"},{"id":"devtools","label":"Developer tools","windows_24h":24,"last_window":"2026-10-02T09:00:00+00:00"},{"id":"indie-saas","label":"Indie SaaS","windows_24h":24,"last_window":"2026-10-02T09:00:00+00:00"}]}2. Check the archive actually reaches that day
`windows_24h` and `last_window` in the step above tell you about now, not about the day you care about. The archive only answers for windows it recorded — it was not running before it started, and no parameter will conjure a window that was never captured. If the date you want predates collection you will get an empty list, which is the same shape as a quiet day.
Watch for: This is the step most people skip, and the one that makes an empty answer look like a finding instead of a gap in coverage.
3. Ask for that single day by interval
`from` and `to` are ISO 8601. Bound them to the day in question rather than pulling a week and filtering client-side: the 5000 series-point cap applies to what the query matches, so a wide interval can truncate the day you actually wanted.
$ curl -H "Authorization: Bearer hk_live_..." \
"https://honesthook.com/api/v1/trends/devtools?from=2026-09-18T00:00:00Z&to=2026-09-19T00:00:00Z"Watch for: `entered_at` and `left_at` on each item tell you whether it was already in the ranking before your window opened. An item with `entered_at` inside the day is a genuine arrival; one with an earlier `entered_at` was already there.
4. Do not try to filter by platform here
`/trends` declares four inputs and `platform` is not one of them. Adding it changes nothing and warns about nothing — you get the unfiltered day back and a filter you believe applied. Group by the `platform` field on each item instead, after the fact.
$ curl "https://honesthook.com/api/v1/trends/ai-agents?hours=168"
{"error":"chave_ausente"}
HTTP 401The shapes that come back
This recipe touches 3 response schemas. Each is documented field by field, generated from the contract and tested against it:
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.
The endpoints used
What this page does not show you
The 200 bodies for the calls that need a key are not transcribed anywhere on this page, and that is deliberate rather than unfinished. Reading them needs a client key, there is no client key on the machine these pages were built from, and an example we never received would be indistinguishable from one we did — to you, and eventually to us. The field-by-field shape is on the schema pages above and is checked against the live contract by a test; an invented example would be checked by nothing.
The other 2 recipes
- Which topics in your niche climbed fastest this weekRank a week of archived history by how much each item actually gained, not by where it sits now. Three calls, one of them free.
- Whether a spike held or decayed within six hoursTwo reads of the same item six hours apart, compared on points — with the trap that makes position look like movement when nothing moved.