API reference

Read-only REST endpoints for creators, search, and pricing. All responses are JSON.

Authentication

Every request must include a Bearer token from /account/api-keys. Tokens look like iu_live_…; the prefix lets you tell live and test keys apart later. Missing or revoked tokens return 401 unauthorized.

curl https://influencerunion.com/api/v1/creators/youtube/mkbhd \
  -H "Authorization: Bearer iu_live_<your_token>"

Rate limits

All authenticated requests are currently uncapped. Per-plan rate limits — and metered usage records — ship alongside billing. Reach out before you scale up so we can flag your account.

GET/api/v1/creators/:platform/:handle

Get a single creator

Returns the creator record, the most recent metrics snapshot, and a fresh pricing range for that platform's canonical format.

curl https://influencerunion.com/api/v1/creators/youtube/mkbhd \
  -H "Authorization: Bearer $IU_KEY"

{
  "data": {
    "creator": {
      "platform": "youtube",
      "handle": "mkbhd",
      "display_name": "Marques Brownlee",
      "subscriber_count": 20900000,
      "view_count": 5380315895,
      ...
    },
    "latest_snapshot": { "captured_at": "...", "avg_views_30d": 3452132, ... },
    "pricing": {
      "format": "video_integrated",
      "tier": "high",
      "basis": "metric_estimate",
      "low_usd": 50000,
      "mid_usd": 86000,
      "high_usd": 129000,
      "sample_size": 0,
      "computed_at": "..."
    }
  }
}

GET/api/v1/creators

List creators (rankings)

Top creators by audience size with optional filters. Same data as /rankings.

platform: optional. youtube | tiktok | instagram | x | bilibili
category: optional. tech, beauty, finance, …
sort: subscribers (default) | views | videos
limit: 1-100, default 20
offset: default 0

curl "https://influencerunion.com/api/v1/creators?platform=youtube&sort=subscribers&limit=10" \
  -H "Authorization: Bearer $IU_KEY"

GET/api/v1/search

Full-text search

Meilisearch-backed search over name, handle, and bio.

q: free-text query (max 200 chars)
platform: optional
category: optional
limit: 1-50, default 20
offset: default 0

curl "https://influencerunion.com/api/v1/search?q=brownlee&platform=youtube" \
  -H "Authorization: Bearer $IU_KEY"

GET/api/v1/pricing

Pricing engine

Two modes. Pass handle to look up a known creator. Or pass raw metrics for an ad-hoc estimate.

platform: required
format: video_integrated (default) | video_dedicated | reel | tweet | …
handle: lookup mode: existing creator handle
subscribers: ad-hoc mode: positive integer
avg_views: ad-hoc mode: optional positive integer
category: ad-hoc mode: optional category

# lookup
curl "https://influencerunion.com/api/v1/pricing?platform=youtube&handle=mkbhd&format=video_integrated" \
  -H "Authorization: Bearer $IU_KEY"

# ad-hoc
curl "https://influencerunion.com/api/v1/pricing?platform=youtube&subscribers=500000&avg_views=200000&category=tech" \
  -H "Authorization: Bearer $IU_KEY"

Error format

All non-2xx responses share the same envelope. Common codes: unauthorized, not_found, bad_platform, bad_format, search_unavailable.

{ "error": { "code": "bad_platform", "detail": "Unknown platform: xyz" } }

Versioning

We pin the major version in the URL (/api/v1). Additive changes — new fields, new endpoints, new filter values — don't bump the version. Anything that removes or renames a field will ship under /api/v2 with a deprecation window on v1.