creators/by-handle

Look up a single creator by their handle on a specific platform. The fastest path when you already have the @-handle and want the full enriched record. One request, one creator.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.swaypi.com/v1/creators/by-handle/tiktok/examplecreator

import requests

def get_creator(platform: str, handle: str, api_key: str) -> dict:
    r = requests.get(
        f"https://api.swaypi.com/v1/creators/by-handle/{platform}/{handle}",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=10,
    )
    if r.status_code == 404:
        return None
    r.raise_for_status()
    return r.json()

creator = get_creator("tiktok", "examplecreator", "YOUR_API_KEY")
if creator:
    print(creator["display_name"], creator["followers"])

async function getCreator(platform, handle, apiKey) {
  const r = await fetch(
    `https://api.swaypi.com/v1/creators/by-handle/${platform}/${encodeURIComponent(handle)}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );
  if (r.status === 404) return null;
  if (!r.ok) throw new Error(`Swaypi ${r.status}`);
  return r.json();
}

const creator = await getCreator("tiktok", "examplecreator", "YOUR_API_KEY");
if (creator) console.log(creator.display_name, creator.followers);

Path parameters

Name	Type	Description
platform	enum	One of `tiktok`, `instagram`, `youtube`, `reddit`, `twitch`, `kick`, `x`, `pinterest`.
handle	string	The creator's handle on that platform. Omit any `@` prefix. Case-insensitive. URL-encode any special characters.

Response

Returns the full enriched creator record. Identical schema to a single item in /v1/creators/search results.

{
  "swaypi_id": "swp_a1b2c3",
  "platform": "tiktok",
  "handle": "examplecreator",
  "display_name": "Example Creator",
  "bio": "Daily makeup tutorials. Drugstore + Sephora reviews.",
  "followers": 124500,
  "following": 312,
  "posts_count": 489,
  "engagement_rate": 0.063,
  "country": "US",
  "region": "CA",
  "niche_tags": ["beauty", "skincare", "wellness"],
  "quality_score": 87,
  "brand_safe": true,
  "is_verified": false,
  "audience_geo": {
    "US_pct": 0.78,
    "CA_pct": 0.09,
    "top_metros": ["Los Angeles", "New York", "Chicago"]
  },
  "audience_age": { "13_17": 0.04, "18_24": 0.42, "25_34": 0.31, "35_plus": 0.23 },
  "contact_email": "[email protected]",
  "last_post_at": "2026-06-14T18:23:00Z",
  "last_indexed_at": "2026-06-14T22:00:00Z"
}

Errors

404 Not Found. The creator either doesn't exist on that platform, has been banned, or hasn't been indexed by Swaypi yet. Submit them via POST /v1/creators/discover (coming soon) to add them to the index.

403 Forbidden. Your tier doesn't include all the fields returned (e.g. contact_email). The fields are omitted, not returned with placeholders.

Performance notes

Handle lookups are the fastest endpoint Swaypi serves — p50 latency is under 80ms. If you're enriching a large list of handles, prefer this endpoint over creators/search for each one. Batch enrichment via POST /v1/creators/enrich (coming soon) is more efficient for runs over 100 handles.

GET /v1/creators/search — when you need to discover creators by filter rather than name.

Authentication — Bearer token setup and per-tier permissions.