Skip to main content

​
Success response (200)

A successful request returns a JSON object with results (array) and count (integer). 
{
  "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,
      "media_count": 523,
      "gender": "male"
    }
  ],
  "count": 1
}

​
Field reference

​
Top-level fields

​
results
array
required
Array of influencer objects matching the search criteria.
​
count
integer
required
Number of results returned. May be less than limit if fewer matches exist.

​
Influencer object fields

​
username
string
required
Instagram handle (without @). Example: "fitnessguru"
​
full_name
string
required
Display name on the Instagram profile. Example: "Alex Fitness"
​
followers
integer
required
Total follower count. Example: 150000
​
following
integer
required
Number of accounts this user follows. Example: 900
​
category
string
Instagram business category. Only present for business/creator accounts. Example: "Fitness"
​
bio
string
Profile bio text. May contain line breaks and emojis. Example: "Personal trainer | Online coaching | NYC"
​
public_email
string
Public contact email. Only present on business accounts that have set a public email. This is the highest-value field for outreach use cases. Example: "alex@fitnessguru.com"
​
is_verified
boolean
required
Whether the account has a verified (blue badge) checkmark. Example: false
​
is_business
boolean
required
Whether the account is a business or creator account (as opposed to personal). Business accounts are more likely to have public_email and category. Example: true
​
media_count
integer
Total number of posts on the account. Useful for gauging activity level. Example: 523
​
gender
string
Predicted gender of the account holder. Values: "male" or "female". Based on profile analysis. Example: "female"

​
Error responses

​
402 Payment Required

Returned on every initial request. Contains payment details for x402 clients. 
{
  "error": "Payment Required",
  "x402": {
    "version": "1",
    "amount": "100000",
    "asset": "USDC",
    "payTo": "0xB1Acd9E0269023546074400A434e703B646AaBBa",
    "chain": "base"
  }
}
Your x402 client library handles this automatically — you don’t need to parse this response manually.

​
422 Validation Error

Returned when request parameters are invalid. 
{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

​
429 Too Many Requests

Returned when rate limits are exceeded. Retry after the duration specified in the Retry-After header.

​
500 Internal Server Error

Unexpected server error. If you see this consistently, please report it at github.com/socialinteldev/social-intel-mcp/issues.