> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# HypeAuditor plugin

> HypeAuditor influencer data - reports, media, audience history, brand mentions, discovery search and saved lists.

Use **HypeAuditor** through Corsair: one client, typed API calls.

HypeAuditor reports on influencer accounts: followers, audience quality, engagement, demographics, brand mentions and growth history. This plugin wraps the v2 API.

Every request needs **two** credentials, issued together for an API subscription: a Client ID and an API token. Store the API token as the account's API key and the Client ID as its `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 a `202` body carrying `retryTtl`, 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.unlockedReports` shows `refunded: true` for 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: true` to 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 `filters` unchanged rather than being modelled field by field, so a filter the provider accepts is never refused here. `social_network` and `page` are 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 `v` parameter defaults to its latest, and `v=1` was deprecated on 2024-08-01. The plugin sends `v=2` on every call, and a `v` passed by a caller cannot override it.
* **One route is spelled differently from its docs page.** The YouTube history action is `auditor.youtube.history`, not `auditor.youtubeHistory`: the latter answers `405` with code `3` (`Unknown method passed`). Every other network answers both spellings.
* **Errors branch on a numeric code.** A failure is `{ error: { code, description } }`. Code `3` means the action name is wrong, `4` means the token is wrong or the account is private or has no posts, and `31` means the account has too few followers. A `402` is 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.

**What you get:**

* 26 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/hypeauditor better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/hypeauditor better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/hypeauditor better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/hypeauditor better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { hypeauditor } from '@corsair-dev/hypeauditor';

export const corsair = createCorsair({
	plugins: [
		hypeauditor(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the HypeAuditor API key before the first call: `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](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> hypeauditor()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**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](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'hypeauditor',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**Read an account's recent media, which costs nothing**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.hypeauditor.api.media.instagram({ channel: 'nasa' });
```

**Read the YouTube report the docs name for testing (free only with HypeAuditor's sandbox credentials)**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.hypeauditor.api.reports.youtube({ channel: 'UCLA_DiR1FfKNvjuUpBHmylQ' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/hypeauditor/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/hypeauditor/api.md)
>
> Every `hypeauditor.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.