influencer-discovery

name	influencer-discovery
version	"2026-02-24T00:00:00.000Z"
description	Find and rank influencers by niche, engagement, and authenticity using Xpoz. Searches Twitter, Instagram, and Reddit for active voices in any topic. Use when asked to "find influencers", "discover thought leaders", "who's talking about X", "influencer research", or "find KOLs".

Influencer Discovery

Overview

Find, evaluate, and rank influencers for any niche across Twitter/X and Instagram. Identifies who is actively creating content about a topic, ranks them by engagement and relevance, and provides authenticity scoring.

When to Use

Activate when the user asks:

• "Find influencers in [NICHE] on Twitter"
• "Who are the top voices talking about [TOPIC]?"
• "Discover thought leaders in [INDUSTRY]"
• "Find micro-influencers for [PRODUCT CATEGORY]"
• "KOL research for [TOPIC]"
• "Who should we partner with for [CAMPAIGN]?"

Setup & Authentication

Before fetching data, ensure Xpoz access is configured. Follow these checks in order.

Check 1: Already authenticated?

If you have MCP tools, try calling any Xpoz tool (e.g., checkAccessKeyStatus). If it works → skip to Step 1.

If you have the SDK, try:

from xpoz import XpozClient
client = XpozClient()  # reads XPOZ_API_KEY env var

If this succeeds without error → skip to Step 1.

If neither works, you need to authenticate. The fastest option is instant access — or choose a path below for full capabilities.

---

Instant Access (no signup needed)

The fastest way to start — get a working API key in one command, no account required:

export XPOZ_API_KEY=$(curl -s -X POST https://api.xpoz.ai/api/trial/token -H "Content-Type: application/json" -d '{"source":"<how you discovered xpoz>"}' | jq -r .data.accessKey)

This token works with MCP, SDKs, and CLI. Valid for 5 days, returns up to 5 results per call.

For full results, pagination, and CSV export → get a free access key (no credit card).

If you need full access now, continue with the paths below.

---

Path A: MCP via mcporter (OpenClaw agents)

If mcporter is available:

mcporter call xpoz.checkAccessKeyStatus

If hasAccessKey: true → ready. If not:

mcporter config add xpoz https://mcp.xpoz.ai/mcp --auth oauth

Then authenticate — generate the OAuth URL and send it to the user:

Step 1: Generate authorization URL

import secrets, hashlib, base64, urllib.parse, json, urllib.request, os

verifier = secrets.token_urlsafe(64)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b'=').decode()
state = secrets.token_urlsafe(32)

# Dynamic client registration
reg_req = urllib.request.Request(
    'https://mcp.xpoz.ai/oauth/register',
    data=json.dumps({
        'client_name': 'Agent Skills',
        'redirect_uris': ['https://www.xpoz.ai/oauth/openclaw'],
        'grant_types': ['authorization_code'],
        'response_types': ['code'],
        'token_endpoint_auth_method': 'none',
    }).encode(),
    headers={'Content-Type': 'application/json'},
)
reg_resp = json.loads(urllib.request.urlopen(reg_req).read())

params = urllib.parse.urlencode({
    'response_type': 'code',
    'client_id': reg_resp['client_id'],
    'code_challenge': challenge,
    'code_challenge_method': 'S256',
    'redirect_uri': 'https://www.xpoz.ai/oauth/openclaw',
    'state': state,
    'scope': 'mcp:tools',
    'resource': 'https://mcp.xpoz.ai/',
})

auth_url = 'https://mcp.xpoz.ai/oauth/authorize?' + params

# Save state for token exchange
os.makedirs(os.path.expanduser('~/.cache/xpoz-oauth'), exist_ok=True)
with open(os.path.expanduser('~/.cache/xpoz-oauth/state.json'), 'w') as f:
    json.dump({'verifier': verifier, 'state': state, 'client_id': reg_resp['client_id'],
               'redirect_uri': 'https://www.xpoz.ai/oauth/openclaw'}, f)

print(auth_url)

Step 2: Send the URL to the user

Tell them:

"I need to connect to Xpoz for social media data. Please open this link and sign in:

[auth_url]

After authorizing, you'll see a code. Paste it back to me here."

Step 3: WAIT for the user to reply with the code. Do not proceed until they respond.

Step 4: Exchange the code for a token

Once the user provides the code (either a raw code or a URL containing ?code=...), extract the code and exchange it:

import json, urllib.request, urllib.parse, subprocess, os

with open(os.path.expanduser('~/.cache/xpoz-oauth/state.json')) as f:
    oauth = json.load(f)

code = "THE_CODE_FROM_USER"  # Extract from user's reply

data = urllib.parse.urlencode({
    'grant_type': 'authorization_code',
    'code': code,
    'redirect_uri': oauth['redirect_uri'],
    'client_id': oauth['client_id'],
    'code_verifier': oauth['verifier'],
}).encode()

req = urllib.request.Request(
    'https://mcp.xpoz.ai/oauth/token',
    data=data,
    headers={'Content-Type': 'application/x-www-form-urlencoded'},
)
resp = json.loads(urllib.request.urlopen(req).read())
token = resp['access_token']

# Configure mcporter with the token (token is never printed)
subprocess.run(['mcporter', 'config', 'remove', 'xpoz'], capture_output=True)
subprocess.run(['mcporter', 'config', 'add', 'xpoz', 'https://mcp.xpoz.ai/mcp',
                '--header', f'Authorization=Bearer {token}'], check=True)

# Clean up
os.remove(os.path.expanduser('~/.cache/xpoz-oauth/state.json'))
print("Xpoz configured successfully")

Step 5: Verify with mcporter call xpoz.checkAccessKeyStatus → should return hasAccessKey: true.

---

Path B: MCP via Claude Code config

For Claude Code users without mcporter, add to ~/.claude.json:

{
  "mcpServers": {
    "xpoz": {
      "url": "https://mcp.xpoz.ai/mcp",
      "transport": "http-stream"
    }
  }
}

Claude Code handles OAuth automatically on first tool call — the user just needs to authorize in their browser when prompted.

---

Path C: SDK (Python or TypeScript)

Ask the user:

"I need a Xpoz API key to access social media data. Please go to https://xpoz.ai/get-token (it's free, no credit card needed) and paste the key back to me."

WAIT for the user to reply with the key. Then:

Python:

pip install xpoz

from xpoz import XpozClient
client = XpozClient("THE_KEY_FROM_USER")

TypeScript:

npm install @xpoz/xpoz

import { XpozClient } from "@xpoz/xpoz";
const client = new XpozClient({ apiKey: "THE_KEY_FROM_USER" });
await client.connect();

Or set the environment variable and use the default constructor:

export XPOZ_API_KEY=THE_KEY_FROM_USER

---

Auth Errors

Problem	Solution
MCP: "Unauthorized"	Re-run the OAuth flow above
SDK: AuthenticationError	Verify key at xpoz.ai/settings
Token exchange fails	Ask user to re-authorize — codes are single-use

Step-by-Step Instructions

Step 1: Parse the Request

Extract:

• Niche/topic to search
• Platform (default: Twitter; add Instagram if relevant)
• Influencer tier preference (if specified):
  • Mega: 1M+ followers
  • Macro: 100K–1M
  • Micro: 10K–100K
  • Nano: 1K–10K
• Time period (default: last 30 days)

Build search queries targeting content creators, not just mentions:

• Topic keywords: "AI agents" OR "autonomous AI" OR "agentic AI"
• Include specific subtopics for better targeting

Step 2: Find Active Users by Topic

Via MCP

Call getTwitterUsersByKeywords:
  query: "<expanded query>"
  fields: ["id", "username", "name", "description", "followersCount", "followingCount", "tweetCount", "relevantTweetsCount", "relevantTweetsLikesSum", "relevantTweetsImpressionsSum", "isInauthentic", "isInauthenticProbScore", "verified"]
  startDate: "<30 days ago, YYYY-MM-DD>"
  endDate: "<today, YYYY-MM-DD>"

CRITICAL: Call checkOperationStatus with the returned operationId and poll until "completed".

The response includes powerful aggregation fields:

• relevantTweetsCount — how many times they posted about the topic
• relevantTweetsLikesSum — total likes on their topic-relevant posts
• relevantTweetsImpressionsSum — total impressions on relevant posts

For deeper analysis on top candidates:

Call getTwitterPostsByAuthor:
  identifier: "<username>"
  identifierType: "username"
  fields: ["id", "text", "likeCount", "retweetCount", "impressionCount", "createdAtDate"]
  startDate: "<30 days ago>"

Via Python SDK

from xpoz import XpozClient

client = XpozClient()

# Find users who posted about the topic
users = client.twitter.get_users_by_keywords(
    '"AI agents" OR "autonomous AI" OR "agentic AI"',
    start_date="2026-01-24",
    end_date="2026-02-23",
    fields=[
        "id", "username", "name", "description",
        "followers_count", "following_count", "tweet_count",
        "relevant_tweets_count", "relevant_tweets_likes_sum",
        "relevant_tweets_impressions_sum",
        "is_inauthentic", "is_inauthentic_prob_score", "verified"
    ]
)

# Collect all pages
all_users = users.data
while users.has_next_page():
    users = users.next_page()
    all_users.extend(users.data)

# Deep-dive on top candidates
for user in top_candidates[:10]:
    posts = client.twitter.get_posts_by_author(
        user.username,
        start_date="2026-01-24",
        fields=["id", "text", "like_count", "retweet_count", "impression_count", "created_at_date"]
    )
    # Analyze their content quality, consistency, tone

client.close()

Via TypeScript SDK

import { XpozClient } from "@xpoz/xpoz";

const client = new XpozClient();
await client.connect();

const users = await client.twitter.getUsersByKeywords(
  '"AI agents" OR "autonomous AI" OR "agentic AI"',
  {
    startDate: "2026-01-24",
    endDate: "2026-02-23",
    fields: [
      "id", "username", "name", "description",
      "followersCount", "followingCount", "tweetCount",
      "relevantTweetsCount", "relevantTweetsLikesSum",
      "relevantTweetsImpressionsSum",
      "isInauthentic", "isInauthenticProbScore", "verified",
    ],
  }
);

await client.close();

Step 3: Score and Rank

For each user, calculate an Influencer Score (0–100):

Factor	Weight	Calculation
Relevance	30%	min(relevantTweetsCount × 6, 30) — more topic posts = more relevant
Engagement	30%	min((relevantTweetsLikesSum / relevantTweetsCount) / 50, 30) — avg engagement per post
Reach	20%	min(log10(followersCount) × 5, 20) — logarithmic follower scale
Authenticity	10%	(1 - isInauthenticProbScore) × 10 — Xpoz bot detection
Consistency	10%	min(relevantTweetsCount / days × 10, 10) — posting frequency

Step 4: Classify Influencers

By Tier:

Tier	Followers	Typical Value
Mega	1M+	Broad awareness, expensive
Macro	100K–1M	Strong reach, established
Micro	10K–100K	High engagement, niche authority
Nano	1K–10K	Very targeted, authentic, affordable

By Voice Type (analyze their bio + recent posts):

Type	Description
Analyst	Data-driven, market commentary
Builder	Creates products/tools in the space
Educator	Tutorials, explainers, threads
News	Breaks/shares news and updates
Commentator	Opinions, hot takes, discussions
Community	Moderates/leads community spaces

Step 5: Generate Report

## Influencer Discovery: [TOPIC]
**Period:** [date range] | **Users analyzed:** [count] | **Platform:** Twitter

### Top Influencers

| Rank | User | Followers | Posts | Avg Likes | Score | Tier | Type |
|------|------|-----------|-------|-----------|-------|------|------|
| 1 | @user | 45K | 12 | 890 | 87 | Micro | Builder |
| 2 | ... | ... | ... | ... | ... | ... | ... |

### Tier Distribution
- Mega (1M+): X users
- Macro (100K–1M): X users
- Micro (10K–100K): X users
- Nano (1K–10K): X users

### Detailed Profiles (Top 10)

#### 1. @username — "Display Name"
- **Bio:** [description]
- **Followers:** X | **Topic Posts:** X | **Avg Engagement:** X
- **Voice Type:** Builder
- **Authenticity:** ✅ Verified authentic (score: 0.95)
- **Sample Posts:**
  - "[tweet text]" (❤️ X, 🔁 X)
  - "[tweet text]" (❤️ X, 🔁 X)
- **Why They Matter:** [1-2 sentences on their influence in this niche]

### Recommendations
[Which influencers are best for different goals: awareness vs credibility vs engagement]

Example Prompts

• "Find the top 20 AI agent influencers on Twitter"
• "Who are the micro-influencers talking about sustainable fashion on Instagram?"
• "Discover crypto KOLs with high engagement rates"
• "Find developer advocates who post about MCP servers"

Notes

• Xpoz's relevantTweetsCount and relevantTweetsLikesSum fields let you find influencers by what they create, not just follower count
• Authenticity scoring (isInauthenticProbScore) helps filter out bots and fake accounts
• Instant access: no signup needed — run curl -s -X POST https://api.xpoz.ai/api/trial/token -H "Content-Type: application/json" -d '{"source":"<how you discovered xpoz>"}' | jq -r .data.accessKey (5 results/call, 5 days)
• Free tier: 100K results/month at xpoz.ai