creators/search

Filter and search the Swaypi creator index by platform, country, region, niche, follower band, engagement rate, quality score, and brand-safety flag. Returns up to 100 matching creators per request.

Request

curl -G "https://api.swaypi.com/v1/creators/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d platform=tiktok \
  -d country=US \
  -d niche=beauty \
  -d min_followers=50000 \
  -d max_followers=500000 \
  -d min_engagement=0.03 \
  -d brand_safe_only=true \
  -d limit=20

import requests

resp = requests.get(
    "https://api.swaypi.com/v1/creators/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "platform": "tiktok",
        "country": "US",
        "niche": "beauty",
        "min_followers": 50_000,
        "max_followers": 500_000,
        "min_engagement": 0.03,
        "brand_safe_only": True,
        "limit": 20,
    },
    timeout=10,
)
resp.raise_for_status()
for creator in resp.json()["results"]:
    print(creator["handle"], creator["followers"])

const params = new URLSearchParams({
  platform: "tiktok",
  country: "US",
  niche: "beauty",
  min_followers: "50000",
  max_followers: "500000",
  min_engagement: "0.03",
  brand_safe_only: "true",
  limit: "20",
});
const r = await fetch(
  `https://api.swaypi.com/v1/creators/search?${params}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
if (!r.ok) throw new Error(`Swaypi ${r.status}`);
const { results } = await r.json();
for (const c of results) console.log(c.handle, c.followers);

Query parameters

Name	Type	Description
platform	enum	One of `tiktok`, `instagram`, `youtube`, `reddit`, `twitch`, `kick`, `x`, `pinterest`. Omit to search across all platforms.
country	enum	`US` or `CA`. Filters by primary country of audience concentration.
region	string	US state code (`CA`, `NY`) or Canadian province (`ON`, `BC`). Returns creators whose top metro maps to that region.
niche	string	A niche tag (`beauty`, `fitness`, `gaming`, `parenting`, etc.). Matches the creator's primary `niche_tags`.
min_followers	integer	Lower bound on follower count on the queried platform.
max_followers	integer	Upper bound on follower count.
min_engagement	float	Lower bound on engagement rate (likes + comments / followers, averaged over recent posts). E.g. `0.03` = 3%.
min_quality_score	integer	Lower bound on Swaypi's 0–100 quality score (composite of authenticity, engagement health, content consistency).
brand_safe_only	boolean	If `true`, returns only creators flagged brand-safe by Swaypi's content classifier.
limit	integer	Max creators to return (1–100). Default 20.
cursor	string	Pagination cursor returned from a prior response. Omit on first request.

Response

{
  "results": [
    {
      "swaypi_id": "swp_a1b2c3",
      "platform": "tiktok",
      "handle": "examplecreator",
      "display_name": "Example Creator",
      "followers": 124500,
      "engagement_rate": 0.063,
      "country": "US",
      "region": "CA",
      "niche_tags": ["beauty", "skincare", "wellness"],
      "quality_score": 87,
      "brand_safe": true,
      "audience_geo": { "US_pct": 0.78, "CA_pct": 0.09 },
      "contact_email": "[email protected]"
    }
  ],
  "next_cursor": "eyJpZCI6IjEyMzQ1In0=",
  "total_estimate": 1840
}

next_cursor is present when more results are available. Pass it back as the cursor parameter to retrieve the next page. total_estimate is an approximate count of all matching creators in the index (not exact — meant for capacity planning).

Errors

400. Invalid parameter (e.g. platform=facebook — not supported). The detail field names the bad parameter.

403. Your tier doesn't include contact_email and the field was omitted; the search still succeeded but at reduced fidelity.

Common patterns

Bulk discovery for an outreach campaign

To enumerate every brand-safe US beauty TikTok creator between 50K and 500K followers, page through with cursor until next_cursor is absent. Cache results — they don't change minute-to-minute.

Real-time gating in a UI

If you're building a search UI, call creators/search on each user query change with a small limit (5–10) and debounce the input. The quality_score filter cuts noise dramatically — start at min_quality_score=70.

GET /v1/creators/by-handle/{platform}/{handle} — when you already have a handle and want the full record.

Authentication — Bearer token setup and per-tier permissions.