# Social Intel API — Full Reference

> Instagram influencer search API. Pay-per-request via x402 (USDC on Base or Solana). No API keys. No subscriptions.

## Links
- Website: https://socialintel.dev
- API base: https://socialintel.dev
- Documentation: https://socialintel.dev/docs
- API Reference: https://socialintel.dev/docs/api-reference/search
- API Reference (static): https://socialintel.dev/api-reference
- OpenAPI JSON: https://socialintel.dev/openapi.json
- Skill manifest: https://socialintel.dev/skill.md
- About: https://socialintel.dev/about
- Pricing: https://socialintel.dev/pricing
- Agent Card: https://socialintel.dev/.well-known/agent-card.json
- MCP server: https://smithery.ai/servers/socialinteldev/social-intel-mcp
- GitHub: https://github.com/socialinteldev/social-intel-mcp
- dev.to: https://dev.to/socialinteldev

## AgentCash Discovery

To use this API with AgentCash:
```bash
npx agentcash@latest discover https://socialintel.dev
```

Or fetch the skill manifest directly:
```
GET https://socialintel.dev/skill.md
```

## Endpoints

### GET /v1/search — Search Instagram influencers
**Dynamic Pricing:** $0.10 for ≤20 results, +$0.002/result above 20.
- 20 results = $0.10 | 50 results = $0.16 | 100 results = $0.26
- Formula: `price = $0.10 + max(0, limit - 20) × $0.002`

**Parameters:**
- `query` (string, optional): Keyword search by name or bio (e.g. "yoga teacher NYC")
- `country` (string, optional): Country — ISO code (US, UK, DE) or full name (United States, Germany)
- `category` (string, optional): Business niche — Beauty, Fitness, Tech, Food, Travel, Fashion, Health, Music, Gaming, etc.
- `gender` (string, optional): "male" or "female"
- `min_followers` (integer, optional): Minimum follower count. Range: 0–1,000,000,000
- `max_followers` (integer, optional): Maximum follower count (micro-influencer discovery). Range: 0–1,000,000,000
- `limit` (integer, optional): Max results to return. Range: 1–100. Default: 20

**Example request:**
```
GET https://socialintel.dev/v1/search?category=Fitness&country=US&limit=10
```

**Example response:**
```json
{
  "results": [
    {
      "username": "fitnessguru",
      "full_name": "Alex Fitness",
      "followers": 150000,
      "following": 900,
      "category": "Fitness",
      "bio": "Personal trainer | Online coaching | NYC",
      "public_email": "alex@fitnessguru.com",
      "is_verified": false,
      "is_business": true
    }
  ],
  "count": 1
}
```

## Search Strategies
- By niche: ?category=Beauty&country=US
- By keyword: ?query=yoga+teacher+NYC
- With filters: ?category=Fitness&gender=female&min_followers=10000
- Micro-influencers: ?category=Tech&max_followers=100000
- Email harvest: category search — business accounts often have public_email

## Agent Workflow Patterns

### Pattern 1: Micro-influencer discovery with emails
Goal: Find female fitness micro-influencers in the US with public contact emails.

```
Step 1 — Broad search:
GET /v1/search?category=Fitness&country=US&gender=female&min_followers=10000&max_followers=100000&limit=100

Step 2 — Filter results client-side:
  leads = [r for r in results if r["public_email"]]

Step 3 — If not enough, try keyword variant:
GET /v1/search?query=fitness+coach&country=US&gender=female&max_followers=100000&limit=100

Total cost: 2 x $0.26 = $0.52 for up to 200 candidates
Typical email yield: 15-25% of accounts are business with public_email
```

### Pattern 2: Fan-out by country for global campaigns
Goal: Build a travel influencer list across 5 markets.

```
Run in parallel (fan-out):
GET /v1/search?category=Travel&country=US&limit=50   -> $0.16
GET /v1/search?category=Travel&country=UK&limit=50   -> $0.16
GET /v1/search?category=Travel&country=DE&limit=50   -> $0.16
GET /v1/search?category=Travel&country=AU&limit=50   -> $0.16
GET /v1/search?category=Travel&country=BR&limit=50   -> $0.16

Total: 5 parallel calls x $0.16 = $0.80 for 250 leads across 5 countries
```

### Pattern 3: Progressive refinement (start broad, narrow if needed)
Goal: Find 20 highly relevant nano-influencers for a yoga brand.

```
Step 1 — Broad ($0.10):
GET /v1/search?query=yoga&country=US&limit=20

Step 2 — Narrow if needed ($0.10):
GET /v1/search?category=Health&query=yoga+teacher&gender=female&min_followers=5000&max_followers=50000&limit=20

Step 3 — Add location if needed ($0.10):
GET /v1/search?query=yoga+NYC&limit=20

Total: max $0.30 using progressive refinement
```

### Pattern 4: Cost-optimized email harvest
Goal: Harvest business emails for B2B outreach.

```
Use limit=100 (max) for best cost efficiency:
GET /v1/search?category=Beauty&country=US&limit=100  -> $0.26 (100 results)

vs. 5 separate limit=20 calls:
5 x $0.10 = $0.50 (same 100 results)

Saving: 48% cheaper with batch approach
Our price: $0.003/result -- vs $3-$10/result for traditional data broker tools
```

### Pattern 5: Verified influencer lookup (brand ambassadors)
Goal: Find verified accounts for premium partnerships.

```
GET /v1/search?category=Fashion&min_followers=500000&limit=50 -> $0.16

Filter client-side: verified = [r for r in results if r["is_verified"]]
Note: is_verified=true indicates blue checkmark accounts
```

## Filter Combination Reference

| Goal | Recommended Filters |
|------|-------------------|
| Micro-influencers (10K-100K) | min_followers=10000, max_followers=100000 |
| Nano-influencers (1K-10K) | min_followers=1000, max_followers=10000 |
| Email leads | category=X + country=Y (business accounts have email ~15-25%) |
| Global list | fan-out: one request per country |
| Verified accounts | min_followers=100000 (high correlation with verification) |
| Gender-specific | gender=male or gender=female |
| Local market | country=US + query=cityname |

## Cost Optimization Tips

1. **Use limit=100** for harvests -- $0.26/batch vs $0.50 for 5x20
2. **Fan-out in parallel** -- simultaneous calls don't stack latency
3. **Filter client-side** after receiving results (is_verified, public_email, follower range)
4. **Progressive refinement** -- start with limit=20 ($0.10), deepen only if needed
5. **Our price**: $0.003/result (100 results / $0.26) vs $3-$10/result for data brokers

## x402 Payment Flow
1. Send GET request to /v1/search with query parameters
2. Receive 402 Payment Required — body contains payment instructions and accepted chains
3. Pay USDC on Base (EVM) or Solana to the seller wallet
4. Resend original request with payment-signature (or x-payment) header
5. Receive JSON results

## Supported Chains
- **Base (EVM)**: USDC, wallet 0xB1Acd9E0269023546074400A434e703B646AaBBa
- **Solana**: USDC, wallet Fj2MVB43hefNzf2XtJp9wGYqS6zHyLzewZ2Vbo4EmBvV

## Use Cases
- Instagram influencer discovery for marketing campaigns
- Lead generation for B2B outreach to creators
- Finding micro-influencers by niche, location, and max follower count
- Competitor audience and brand ambassador research
- Email harvesting from public business profiles

## MCP Server
Available as MCP server for Claude Desktop, Cursor, and other AI tools:
```json
{
  "mcpServers": {
    "social-intel": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {"SOCIAL_INTEL_API_URL": "https://socialintel.dev"}
    }
  }
}
```
Smithery: https://smithery.ai/servers/socialinteldev/social-intel-mcp