Building an Influencer Discovery Tool: The Complete API Guide

An influencer discovery tool has one job: turn a pile of handles into ranked, enriched creator records — followers, verified status, real engagement, niche, audience demographics, brand fit, and a way to reach them. The catch is that no single vendor endpoint hands you an "influencer object." You compose it from a few cheap primitives, and the quality of your tool is mostly the quality of that pipeline.

This guide builds the whole thing on virev.ai — one Authorization: Bearer $VIREV_API_KEY header, one { data, meta } envelope on every response. The pattern is a funnel: fan out cheaply across all seeds, score them locally, then spend real money only on the shortlist. The same shape works across Instagram, TikTok, and YouTube, so you write it once.

The shape of a discovery pipeline

Every discovery tool is the same five stages. The trick is ordering them by cost: the wide, cheap stages run on everyone; the narrow, expensive stages run only on survivors.

1. 1

   Seed

   Start with usernames — a CSV, a competitor follower export from /v1/instagram/followers, or hashtag scrapes. Anything with a handle.
2. 2

   Resolve

   GET /v1/live/instagram/profile turns each handle into followers, verified status, and the 12 most recent posts. $0.0005 per handle — runs on everyone.
3. 3

   Score

   Compute engagement from those 12 posts with zero extra calls. Drop everyone below your threshold before you spend another cent.
4. 4

   Enrich

   Run /v1/intelligence/profile on survivors only: niche, demographics, brand-fit, commercial intent. $0.05 each — runs on the shortlist.
5. 5

   Contact

   Pull emails and cross-platform socials for finalists from the same AI bundle, or the dedicated /v1/intelligence/contact endpoint.

Step 1: Resolve seed handles into profiles

The q parameter accepts a bare username, an @handle, or a full instagram.com/username URL — so you can pass whatever your seed list already contains without normalizing it first. Each call returns the canonical account; fetch a separate 12-post timeline sample for scoring in the next step.

curl "https://api.virev.ai/v1/live/instagram/profile?q=nike" \
  -H "Authorization: Bearer $VIREV_API_KEY"

The response envelope tells you what it cost and what is left, so you can meter spend per run:

{
  "data": {
    "full_name": "Nike",
    "username": "nike",
    "is_verified": true,
    "edge_followed_by": { "count": 302000000 },
    "edge_follow": { "count": 128 },
    "edge_owner_to_timeline_media": {
      "count": 1204,
      "edges": [ /* 12 most recent posts, each node with edge_liked_by / edge_media_to_comment */ ]
    }
  },
  "meta": { "cost": "$0.0005", "balance": "$9.9995", "request_id": "req_..." }
}

Step 2: Score engagement, then enrich the shortlist

Resolve the canonical profile first, then request a 12-post canonical timeline sample. Average likes-plus-comments across the posts, divide by followers, and gate on it. The two calls cost $0.001 together and preserve the exact profile and timeline evidence separately—use this inexpensive filter before the AI stage.

const API = "https://api.virev.ai";
const headers = { Authorization: "Bearer kb_live_..." };

async function resolveCandidate(handle) {
  const profileRes = await fetch(
    API + "/v1/live/instagram/profile?q=" + encodeURIComponent(handle),
    { headers }
  );
  // 404 = no such handle; skip it (it cost nothing). A transient 502/504 costs
  // nothing either — throw so the caller can retry instead of silently dropping
  // a real creator.
  if (profileRes.status === 404) return null;
  if (!profileRes.ok) throw new Error("resolve failed for " + handle + ": " + profileRes.status);
  const postsRes = await fetch(
    API + "/v1/live/instagram/posts?q=" + encodeURIComponent(handle) + "&limit=12",
    { headers }
  );
  if (!postsRes.ok) throw new Error("posts failed for " + handle + ": " + postsRes.status);
  const profile = (await profileRes.json()).data;
  const posts = (await postsRes.json()).data.posts;
  return { profile, posts };
}

// Average engagement across a separately fetched canonical post batch.
function engagementRate(profile, posts) {
  const followers = profile.followers ?? 0;
  if (!posts.length || !followers) return 0;
  const avg =
    posts.reduce((sum, post) => sum + (post.likes ?? 0) + (post.comments ?? 0), 0) /
    posts.length;
  return avg / followers;
}

async function shortlist(handles, minRate = 0.02) {
  const out = [];
  for (const h of handles) {
    const candidate = await resolveCandidate(h);
    if (candidate && engagementRate(candidate.profile, candidate.posts) >= minRate) {
      out.push(candidate.profile);
    }
  }
  return out; // only these get the $0.05 AI pass
}

For the precise, edge-case-safe engagement formula (reels vs. carousels, verified inflation, follower-band benchmarks), see the Instagram engagement rate API guide. Now enrich the survivors. The /v1/intelligence/profile endpoint layers an LLM over the profile and returns structured niche, demographics, and brand-fit fields — the columns that make a discovery tool actually useful for filtering.

import requests

API = "https://api.virev.ai"
headers = {"Authorization": "Bearer kb_live_..."}

def enrich(handle):
    res = requests.get(
        f"{API}/v1/intelligence/profile",
        params={"q": handle},   # add model="gpt-5.4" for the $0.10 tier
        headers=headers,
        timeout=300,            # the LLM step can take minutes
    )
    res.raise_for_status()
    ai = res.json()["data"]
    return {
        "niche": ai["content_tags"],          # [{ primary, sub_niches }]
        "audience": {
            "age_range": ai["age_range"],
            "country": ai["country"],
            "gender": ai["gender"],
        },
        "brand_fit": ai["brand_fit_summary"],
        "intent": ai["commercial_intent"],
        "authority": ai["niche_authority"],
        "emails": ai["emails"],
        "socials": ai["social_accounts"],
    }

Step 3: Surface contacts for the finalists

The intelligence bundle above already carries emails[] and social_accounts[], so for most creators you get contacts for free as part of enrichment. When you need to dig harder on your top finalists, the dedicated contact endpoint runs an agentic search across their footprint. turns controls how hard it looks (1–5, default 3), and source=live forces a fresh crawl at double the price.

# Deeper contact discovery for a finalist — emails + cross-platform socials
curl "https://api.virev.ai/v1/intelligence/contact?q=zoebakes&turns=3" \
  -H "Authorization: Bearer $VIREV_API_KEY"

This is the stage to run last and narrowest. At $0.10 a call ($0.20 with source=live), contact discovery on 50 finalists is $5.00 — the same order of magnitude as your AI pass, so keep it on the very top of the funnel.

Going cross-platform: TikTok and YouTube

The same envelope and the same q rules extend to other networks, so a multi-platform discovery tool is the same loop with a different base path. TikTok mirrors Instagram closely; YouTube has one important quirk.

# TikTok — q accepts username, @handle, or a tiktok.com/@handle URL
curl "https://api.virev.ai/v1/tiktok/profile?q=@khaby.lame" \
  -H "Authorization: Bearer $VIREV_API_KEY"

# YouTube — q is CASE-SENSITIVE: @handle, a UC... channel id, or a URL
curl "https://api.virev.ai/v1/youtube/profile?q=MrBeast" \
  -H "Authorization: Bearer $VIREV_API_KEY"

What a full run costs

Here is the whole pipeline priced out, with the stage each call runs on. Read it top to bottom as the funnel: cheap and wide at the top, expensive and narrow at the bottom.

Default rate limit is 100 requests/minute, surfaced in the X-RateLimit-* headers; a 429 carries a Retry-After you should honor with backoff. Because failed lookups are free, you can be aggressive on the wide stages and let the funnel absorb bad seeds. If you are optimizing spend, the pricing breakdown has the per-1,000 math, and the creator classification guide covers the intelligence fields in depth.