Docs › Creators · by-handle

GET/v1/creators/by-handle/{platform}/{handle}

creators/by-handle

Swaypi looks 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.

Written and maintained by the Swaypi API team.

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

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.

FAQ

How do I look up a creator by their handle?

Call GET /v1/creators/by-handle/{platform}/{handle} with your Bearer token. Drop any @ prefix; handles are case-insensitive. You get back the full enriched record — the same schema as a single creators/search result.

What happens if the creator isn't in Swaypi's index?

The endpoint returns 404. That means the creator doesn't exist on that platform, has been banned, or hasn't been indexed yet. Handle your 404s so a missing creator doesn't break your pipeline.

Is by-handle faster than search for enriching known handles?

Yes. Handle lookups are the fastest endpoint Swaypi serves, with p50 latency under 80ms. For handles you already have, prefer by-handle over running a search for each one.

Related

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

Authentication — Bearer token setup and per-tier permissions.