Swaypi API documentation
A REST API delivering vetted North American creator data across TikTok, Instagram, YouTube, Reddit, Twitch, Kick, X, and Pinterest. All endpoints return JSON. Authentication is a bearer token. Currently in private beta.
Base URL
https://api.swaypi.com/v1
All endpoints are versioned under /v1. We commit to backward-compatible changes within a major version; breaking changes go to /v2 with at least 90 days of overlap.
Authentication
Every endpoint except /status requires a Bearer token in the Authorization header. Keys are tied to a tier (free, builder, studio, platform) which controls rate limits, batch sizes, and whether contact-email fields are included in responses.
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.swaypi.com/v1/me
See authentication for token lifecycle, rotation, and per-tier permissions.
Endpoints
| Endpoint | What it does |
|---|---|
| GET/me | Returns the calling API key's tier and rate-limit ceiling. |
| GET/creators/search | Search creators by platform, country, niche, follower band, engagement, quality score, brand-safety flag. |
| GET/creators/{id} | Look up a single creator by Swaypi internal ID. Returns the full enriched record. |
| GET/creators/by-handle/{platform}/{handle} | Look up a creator by their handle on a specific platform — fastest path when you already have the @-handle. |
| GET/status | Liveness check. Returns service health + dependency status. No auth required. |
Response shape
All success responses return JSON. Errors return a standard envelope with HTTP status, an error string, and a detail field when available.
{
"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, "top_metros": ["Los Angeles", "New York"] },
"contact_email": "[email protected]"
}
Rate limits
Each tier has its own per-minute rate limit. The current ceiling and remaining budget for the calling key is returned in response headers:
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1718480760
Exceeding the limit returns 429 Too Many Requests. Free tier is 60 req/min and 100 req/day; paid tiers scale up. Batch endpoints (where applicable) count as one request regardless of batch size.
Supported platforms
The platform parameter accepts: tiktok, instagram, youtube, reddit, twitch, kick, x, pinterest. New platforms are added periodically — see GET /platforms (coming soon) for the current authoritative list.
Errors
| Code | Meaning |
|---|---|
| 400 | Bad request — usually a malformed parameter. Check the detail field. |
| 401 | Missing or invalid API key. Verify the Authorization header. |
| 403 | Your tier does not include access to this field or endpoint (e.g. contact_email on the free tier). |
| 404 | Creator not found. The handle may be incorrect, banned, or not yet in the Swaypi index. |
| 429 | Rate limited. Back off and retry after X-RateLimit-Reset. |
| 500 | Internal error. Retry with exponential backoff; if it persists, check status. |
Getting an API key
Swaypi is in private beta. Join the waitlist for an early-access invitation. Once admitted, you can generate a key in the dashboard and rotate it at any time.