client_id. They are sent as X-Auth-Id and X-Auth-Token. The docs note that the token changes when the account password changes.
Things to know before you call:
- Reports spend credits. The first request for a creator costs one credit, taken at the moment of the request, before the report exists. A second request for the same creator is free while the report stays unlocked, which is one year: a request after 365 days costs another credit.
type: 'report'is the mini report and costs a mini-report credit;advanced_report, the default, costs a full one. A report may answer with a202body carryingretryTtl, the seconds to wait before asking again, so the result is either the report or that pending notice. - A failed build is refunded. If the report cannot be built, the credit is returned, and
account.unlockedReportsshowsrefunded: truefor it. That is the read to check when a credit seems to have gone. - Discovery is charged per page, 20 rows at a time. The result is capped at 10,000 rows, so the highest page is 500. Pass
sandbox: trueto validate a request and get sample data without spending a call. - Discovery filters are passed through. The docs list 46 filters, each available on a different subset of networks and plans, and the table changes between releases. They go in
filtersunchanged rather than being modelled field by field, so a filter the provider accepts is never refused here.social_networkandpageare checked, because the docs give them a fixed set and a maximum. - Media, mentions, lists and account reads are free. They change nothing and are safe to retry. Media needs the report unlocked already.
- History reads unlock the report. HypeAuditor documents that a metrics-history request unlocks the creator’s report, so the first one for a creator spends a credit, like a report read. Repeating it is free.
- The version is pinned. HypeAuditor’s
vparameter defaults to its latest, andv=1was deprecated on 2024-08-01. The plugin sendsv=2on every call, and avpassed by a caller cannot override it. - One route is spelled differently from its docs page. The YouTube history action is
auditor.youtube.history, notauditor.youtubeHistory: the latter answers405with code3(Unknown method passed). Every other network answers both spellings. - Errors branch on a numeric code. A failure is
{ error: { code, description } }. Code3means the action name is wrong,4means the token is wrong or the account is private or has no posts, and31means the account has too few followers. A402is an exhausted balance or an expired subscription, which no retry can fix. - The documented limit is just under 100 requests a minute.
- No inbound webhooks. The API documents none, so this plugin registers no webhook route.
- 26 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the HypeAuditor API key before the first call: More: API Key
pnpm corsair setup --plugin=hypeauditor --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Read an account’s recent media, which costs nothingWhat’s next
API reference
Every
hypeauditor.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.