Twitch Profile
A public Twitch profile can expose a username, display name, biography, profile imagery, website, verification or privacy signals, location context, and visible account counts. The normalized account record supports creator enrichment, profile checks, and repeatable public-data snapshots without providing channel management or authenticated account actions.
Twitch Profile API Features
- Exact username lookupSubmit one required username to the Twitch Profile API using 1 to 64 supported characters, with an optional single leading @.
- Normalized public identityRead the available profile ID, public URL, username, display name, biography, avatar, cover image, and website in the AccountItem contract.
- Account state signalsKeep the available verified and private flags as nullable fields instead of inferring values when the provider does not expose them.
- Visible profile metricsUse available follower, following, and post counts as separate optional metrics tied to the collection time.
- Asynchronous task flowSubmit the username, retain task_id, poll the shared task reader, and retrieve the stored normalized result after success.
- Fixed request billingA successful task has a fixed cost of 0.19 SocQ credits, independent of optional field availability.
Twitch Profile API Parameters
| Parameters | Required | Description |
|---|---|---|
username | Required | Required Twitch username. After trimming, it may begin with one @ and must then contain 1 to 64 ASCII letters, numbers, dots, underscores, or hyphens. |
How to Use the Twitch Profile API
Submit one supported Twitch username to the Twitch Profile API, track the asynchronous task, and read the single stored profile result through the shared cursor response.
- Choose one public Twitch username that matches the supported character rule.
- POST username to /v1/twitch/profile and save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or reports a failure.
- Read data.results.items; the profile lookup produces at most one source record, while the stored result envelope still includes has_more and next_cursor.
curl -X POST "https://api.socq.ai/v1/twitch/profile" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"ninja"}'
# Poll GET /v1/tasks/{task_id}
# Read the normalized account in data.results.itemsTwitch Profile API Use Cases
- Creator record enrichment: Add available Twitch identity, biography, imagery, website, account flags, and public counts to a known creator record.
- Username verification workflows: Resolve a submitted handle into a normalized public profile before linking it to an internal entity or research subject.
- Public account comparisons: Compare visible follower, following, and post counts across separately submitted usernames using the same AccountItem shape.
- Profile change monitoring: Store nullable identity fields and metrics with collected_at so later runs remain distinguishable public snapshots.
Twitch Profile API Pro Tips
- Submit a username rather than a Twitch channel URL; url and results_limit are not accepted request fields for this endpoint.
- Use only one optional leading @; spaces, slashes, non-ASCII characters, and repeated @ characters fail the runtime username rule.
- Expect zero or one source profile record. Do not interpret the task reader's limit parameter as a way to expand a profile into videos or followers.
- Treat the ID, URL, biography, images, website, account flags, location, and each metric as nullable, and preserve collected_at for snapshot comparisons.
- Use separate Twitch content endpoints when available for videos or clips; this endpoint is read-only profile lookup and does not log in, publish, moderate, or manage a channel.
Related APIs
Beyond the Twitch Profile API, use these APIs when you need a different type of public Twitch data.
- Twitch User Videos API
- Twitch Clip Downloader API — Fetch one public Twitch clip from its clip URL with title, views, length, creation time, broadcaster profile, and a downloadable MP4 link with thumbnail.