Twitch Profile API
Look up a public Twitch channel by login and get a structured profile card, follower count, live signals, and a recent-video sample in the shared Social Fetch JSON envelope.
GET /v1/twitch/profiles/{handle}1 credit per successful request.
About this endpoint
Sponsorship pipelines and streamer directories usually start with a Twitch login, not a Helix user id. You need the public card: display name, bio, avatar, partner flag, whether the channel is live, follower count, and enough recent VOD context to decide whether to spend more credits on schedule or video lists.
`GET /v1/twitch/profiles/{handle}` takes the channel login (with or without a leading `@`) and returns the shared envelope. Branch on `data.lookupStatus` before you write rows — `found` and `not_found` are explicit. On `found`, `data.profile` carries handle, displayName, bio, avatarUrl, bannerUrl, profileUrl, platformUserId, isPartner, isLive, currentViewersCount, and socialLinks; `data.metrics` holds followers; `data.recentVideos` and `data.similarStreamers` arrive when Twitch exposes them.
This route is the identity-and-live card for one handle. Full VOD lists and schedule payloads are separate paths on the Twitch hub. Pricing is on the credit badge for this operation; bill from `meta.creditsCharged`. on every response. Keep `meta.requestId` when a row looks wrong.
Twitch Profile API FAQ
How do I get a Twitch profile by handle via API?
Call `GET /v1/twitch/profiles/{handle}` with your Social Fetch API key (`x-api-key`). Pass the Twitch login as the path parameter, with or without a leading `@`. Read `data.lookupStatus`, then `data.profile` and `data.metrics` when the channel is available.
How much does the Twitch Profile API cost?
Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.
What does the Twitch Profile API return?
On `found`, a profile card under `data.profile` (handle, display name, bio, avatar and banner URLs, profile URL, Twitch user id, partner flag, live flag, current viewer count, social links) plus `data.metrics.followers`, a `data.recentVideos` sample, and `data.similarStreamers` when available. The envelope also includes `data.lookupStatus`, `meta.requestId`, and `meta.creditsCharged`.
What happens if the Twitch handle does not exist?
`data.lookupStatus` is `not_found`, and profile and metrics are null. Do not invent follower counts or bios. Always branch on `lookupStatus` before treating the row as a found channel.
Do I need a Twitch client ID or Helix OAuth?
No. You authenticate to Social Fetch with an API key. The route reads public channel data for enrichment-style lookups. Use Twitch Helix and EventSub directly when you need apps, bots, or realtime pubsub.
How is this different from listing a channel's videos or schedule?
This route returns the channel card, live signals, follower metrics, and a recent-video sample. Full VOD pagination is `GET /v1/twitch/profiles/{handle}/videos`. Schedule is `GET /v1/twitch/profiles/{handle}/schedule`. Call the profile route first when you need an explicit `lookupStatus` before interpreting an empty list.
Can I use the Twitch Profile API in a creator database?
Yes. Teams use it to upsert streamer rows (followers, partner status, live state, linked social URLs) and to confirm a login exists before spending credits on videos, schedule, or clips. The same envelope shape works next to YouTube and TikTok profile lookups on one key.