> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/twitch/profiles-handle>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/twitch/profiles-handle.mdx>

---

# 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}` 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. Bill from `meta.creditsCharged`. Keep `meta.requestId` when a row looks wrong.

## Request

- **Endpoint:** `GET /v1/twitch/profiles/{handle}`
- **Credits:** 1 credit
Failed requests are free
- **Input:** by handle
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/twitch/profiles/handle/get)
- **Platform page:** [/platforms/twitch](https://www.socialfetch.dev/platforms/twitch)

## 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.