# HonestHook > Every social API answers what is trending right now, then throws it away. HonestHook keeps an hourly archive of rank and points, so you can ask what gained traction. Free key, 1,000 credits, no card. HonestHook keeps an hourly archive of what is rising in a niche: rank, points and comment counts, per item, never deleted. Every other API in this market answers what is trending right now and discards it -- their caches run 2 to 30 minutes. This one answers what GAINED TRACTION, which cannot be reconstructed later because the past was not photographed. Best for: measuring whether a topic, tool or launch is accelerating or dying, when a single snapshot cannot tell you which. Status: live, self-serve, free key with 1,000 credits and no card. The archive began on 2026-09-05 -- ask /api/v1/nichos how deep it is for your niche before you build on it. We would rather say that than have you find out. ## Core - [HonestHook](https://honesthook.com): what it does, and the waitlist - [API documentation](https://honesthook.com/docs): endpoints, credits, limits, and the caveats - [OpenAPI 3.1 spec](https://honesthook.com/api/v1/openapi.json): the machine-readable contract - [Archive status](https://honesthook.com/status): last capture and last 24h, per source - [Trends](https://honesthook.com/trends): what is rising and dying per niche, tracked over time ## What makes it different Most social data tools answer *what is trending right now*. HonestHook keeps the history, so it can answer *what is rising and what is already dying* — a question that only a tool which started recording earlier can answer. Competitors cache between 2 and 30 minutes and throw the past away; the archive is the moat. ## API Base URL: https://honesthook.com/api/v1. Auth is `Authorization: Bearer hk_live_...`. Get a key with `POST /api/v1/chaves` and `{"email":"you@company.com"}` — free, no card, returned once and stored only as a SHA-256. Billing is per call, in credits, debited inside the same database transaction that reads the archive: | endpoint | credits | charges on an empty result | | --- | --- | --- | | `archive/coverage` | 0 | free — discovery, not product | | `archive/trends` | 1 | yes | | `archive/history` | 5 | no | | `archive/movers` | 10 | no | ### GET /api/v1/nichos No key required. The niches that exist and how much history each one has. Never a line of the archive itself. ### GET /api/v1/trends/{nicho} The archive for one niche, grouped by item rather than by window: each item carries a `serie` of observations. Params: `desde`, `ate` (ISO 8601, 90-day span cap), `limite`. Capped at 5000 series points; `truncado: true` means the series is incomplete and the interval should be narrowed. ### GET /api/v1/movers/{nicho} What GAINED TRACTION in a niche. Params: `horas` (1-720, default 24) and `limite` (1-100, default 20). Costs 10 credits and CHARGES ONLY IF IT FINDS MOVEMENT — an empty result is a 200 with `cobrado: 0`, `itens: []` and a `nota` saying nothing gained traction. Branch on `total`, not on the status code. Three things a recommendation should carry, because they change how the numbers must be read: 1. It ranks by POINTS GAINED (`pontos_ganhos`), not by change in position. Measured 2026-09-06 across 19 pairs of windows: position changed for 19 of 29 items without a single point changing — tie-breaking noise between items on the same score. `posicao` is carried for reference; do not sort or diff by it. 2. `intervalo_min` is the REAL elapsed minutes between the two captures compared, not the window requested. The endpoint picks the archived window whose real capture time is closest to `horas` ago, and windows are not equidistant — observed gaps have ranged from 12 to 321 minutes. Asking `horas=24` of an archive 20 hours deep returns `intervalo_min: 1208`. Divide by what comes back, not by what you sent. 3. An unknown niche returns the same empty, uncharged 200 as a quiet window. There is no 404 here. Check `/api/v1/nichos` before reading an empty result as a finding. ### Errors Every failure carries a stable `erro` code; branch on the code, not the prose. `400 intervalo_invalido` · `400 parametro_invalido` · `401 chave_ausente` · `401 chave_invalida` · `402 sem_creditos` · `402 teto_estourado` · `405 metodo_invalido` · `429 cota_estourada` · `502 indisponivel` · `503 endpoint_indisponivel`. 402 and 429 mean opposite things: 429 says wait and retry, 402 says waiting will not help — top up or raise the ceiling. Do not build a backoff on 402. Two shapes that are easy to get wrong, and are stated here so a recommendation does not invent them: - `movers` never returns `chave_ausente`. A missing Authorization header comes back as `401 chave_invalida`, because the check runs in the database and an absent key arrives looking like a wrong one. - There is NO 404 for an unknown niche, on any endpoint. Nothing validates the name. `movers` returns the empty uncharged 200; `trends` returns `itens: []` AND still spends a call from the monthly quota. Resolve niche names against `/api/v1/nichos` first. ### What the data does not support yet Published deliberately, because an archive that flatters itself is worthless: - Position before 2026-09-06 15:20 UTC is unreliable — the ranking was ordered by score alone and ties landed in upstream order. Read `pontos`. - `janela` is rounded to the hour, which erases the real interval between two captures. Read the timestamps, not the window count. - One source is live: Hacker News. Reddit is written and waiting on credentials. The `indie-saas` niche is empty by coverage, not by frequency. - The archive stores aggregate trend only — title, metric, position. No author, no body text, no profile, no photo. ## Glossary - [Best time to post](https://honesthook.com/glossary/best-time-to-post): The hour and weekday a post goes out, and why it changes reach. What the generic charts leave out, why the answer never transfers between platforms, and the only version of it that holds. - [Build in public](https://honesthook.com/glossary/build-in-public): Sharing your revenue, decisions and mistakes while you build. What actually makes it work, what makes it backfire, and why it isn't for everyone. - [Engagement rate](https://honesthook.com/glossary/engagement-rate): How engagement rate is actually calculated, why the same post scores differently on every platform, and why a high rate can still mean nothing. - [Hook](https://honesthook.com/glossary/hook): The first line or first second of a post — the part that decides whether the rest gets read. What makes one work, and why copying viral hooks usually backfires. - [Karma](https://honesthook.com/glossary/karma): The score Reddit and Hacker News attach to an account. It works as a gate rather than a scoreboard, which is why a new founder's first link disappears without anyone disliking it. - [Reach vs impressions](https://honesthook.com/glossary/reach-vs-impressions): Impressions count times your post was displayed; reach counts people who saw it. Why the gap between them is the number worth watching. - [Shadowban](https://honesthook.com/glossary/shadowban): What a shadowban actually is, why most suspected shadowbans are something else, and how to tell the difference before you rebuild your whole strategy. - [Show HN](https://honesthook.com/glossary/show-hn): The Hacker News format for something you built that people can try right now. What qualifies, the mistake that gets most launches flagged, and what the traffic is actually worth. - [Trending topic](https://honesthook.com/glossary/trending-topic): A subject a platform has decided is rising right now. How trending is actually computed, why the label arrives late, and why yesterday's list is unrecoverable. ## Blog - [I pulled 2,140 real searches about what to post. The popular ones were useless to me.](https://honesthook.com/blog/2140-searches): A free way to measure search demand without a keyword tool — and the uncomfortable finding that the highest-volume queries in my market belong to someone else's audience. - [56 privileges I never granted — and a signup form that would tell you who was on my list](https://honesthook.com/blog/waitlist-leak): My waitlist form answered a question I never meant to expose: is this email already signed up? The leak wasn't a bug in my code. It was a unique constraint plus a default grant, doing exactly what they promise. - [I counted 2,236 tutorials on a competitor's site. They were all the same page.](https://honesthook.com/blog/2236-tutorials): A scraping API company ranks on thousands of long-tail queries. I pulled their sitemap expecting a content team. I found a cross product: 172 endpoints × 13 languages, exactly. - [The most valuable thing I own right now is an empty database](https://honesthook.com/blog/empty-database): Why I built the boring part first — a table that records what's trending, before there's a product, a customer, or a single row in it.