Look up any viewer
One person and their standing on this channel, per platform account - signed in to the tip page or not. viewer is the person (whether and when they signed in here); platforms.twitch and platforms.kick are their account on each platform with its standing on this channel there - follow, current sub, best known sub length, moderator, VIP and chat activity - or null where the person has no known account on that platform. credits, grants and usage are the sub-rewards picture (credits are earned by subbing, so someone who never signed in can hold them too). A person who linked both accounts gets both blocks, and everything is read across the pair. Requires viewers:read.
{user} takes twitch:<id or login>, kick:<id or login>, a viewer id (v_..., as viewer.id answers), or a bare id or login - tried against the channel’s signed-in viewers first, then as a Twitch account, then a Kick one.
Sub length. Twitch’s API has no way to ask how long someone has been subscribed, so sub_months is the most TipPage has seen: the subscriber badge on their latest chat line (needs the chat bot on for that platform) or their latest shared resub, whichever says more, with sub_months_at saying when it was seen - add the months since then if they are still subscribed. On Kick it comes from Kick directly. null = never seen.
Moderator and VIP are read live: Twitch with the owner’s grant (null when the channel owner has not reconnected since those scopes were added), Kick from kick.com’s channel record.
/viewers/{user}AuthorizationBearer token (tp_live_... or tpat_...) · headerrequiredA TipPage API key (tp_live_..., created in Dashboard → Settings → Developer) or an OAuth 2.0 access token (tpat_..., see the OAuth guide). Both carry the same scopes and are accepted on every endpoint.
userstringrequiredtwitch:<id or login>, kick:<id or login>, v_..., or a bare id or login (see above).
The viewer.
viewerViewerPersonrequiredThe person a viewer lookup answered for. Their name and picture are those of the account they signed in with here most recently (the account that was looked up when they never did); the dates roll up over every account of theirs that signed in.
Show propertiesHide properties
idstring | nullrequiredTipPage's id for the person - stable across their linked accounts and every tip page, and accepted as {user}. null when they have never signed in to any tip page.
signed_inbooleanrequiredWhether any account of theirs has signed in to THIS tip page.
signed_in_withstring | nullrequiredThe platform of their most recent sign-in here.
twitchkicknulldisplay_namestring | nullrequiredprofile_image_urlstring<uri> | nullrequiredfirst_signed_in_atstring<date-time> | nullrequiredTheir first sign-in to this tip page, on any account.
last_active_atstring<date-time> | nullrequiredLast account activity seen here (profile refreshes included).
platformsobjectrequiredThe person's account per platform, with its standing on this channel there. null = no known account on that platform.
Show propertiesHide properties
twitchViewerPlatform | nullrequiredShow propertiesHide properties
idstringrequiredThe platform's user id.
loginstring | nullrequireddisplay_namestring | nullrequiredprofile_image_urlstring<uri> | nullrequiredsigned_inbooleanrequiredWhether THIS account has signed in to the tip page.
followingboolean | nullrequiredfollowed_atstring<date-time> | nullrequiredsubscribedboolean | nullrequiredRead live; when the live read fails on an account that signed in here, the tier the sign-in recorded stands in.
tierinteger | nullrequiredCurrent sub tier (Kick has no tiers - always 1).
123nullgiftedboolean | nullrequiredTwitch only - the current sub is a gift.
gifter_loginstring | nullrequiredsub_monthsinteger | nullrequiredCumulative sub months as last seen (see the operation).
sub_months_atstring<date-time> | nullrequiredWhen sub_months was seen.
sub_months_sourcestring | nullrequiredchat = their subscriber badge in chat, resub = a shared resub, kick = read from Kick.
chatresubkicknullmoderatorboolean | nullrequiredA moderator of this channel on that platform.
vipboolean | nullrequiredA VIP of this channel on that platform.
chatobjectrequiredShow propertiesHide properties
messagesintegerChat messages counted on this channel from this account.
first_seenstring<date> | nullFirst day they chatted.
last_seen_atstring<date-time> | nullnullkickViewerPlatform | nullrequiredShow propertiesHide properties
idstringrequiredThe platform's user id.
loginstring | nullrequireddisplay_namestring | nullrequiredprofile_image_urlstring<uri> | nullrequiredsigned_inbooleanrequiredWhether THIS account has signed in to the tip page.
followingboolean | nullrequiredfollowed_atstring<date-time> | nullrequiredsubscribedboolean | nullrequiredRead live; when the live read fails on an account that signed in here, the tier the sign-in recorded stands in.
tierinteger | nullrequiredCurrent sub tier (Kick has no tiers - always 1).
123nullgiftedboolean | nullrequiredTwitch only - the current sub is a gift.
gifter_loginstring | nullrequiredsub_monthsinteger | nullrequiredCumulative sub months as last seen (see the operation).
sub_months_atstring<date-time> | nullrequiredWhen sub_months was seen.
sub_months_sourcestring | nullrequiredchat = their subscriber badge in chat, resub = a shared resub, kick = read from Kick.
chatresubkicknullmoderatorboolean | nullrequiredA moderator of this channel on that platform.
vipboolean | nullrequiredA VIP of this channel on that platform.
chatobjectrequiredShow propertiesHide properties
messagesintegerChat messages counted on this channel from this account.
first_seenstring<date> | nullFirst day they chatted.
last_seen_atstring<date-time> | nullnullcreditsobjectrequiredShow propertiesHide properties
availableintegerCredits spendable right now.
totalintegerCredits ever granted.
usedintegerCredits already spent.
pendingintegerGift-sub credits waiting for their first sign-in to convert (informational - already part of neither total nor available).
grantsobject[]requiredThe award ledger, newest first (up to 100 rows).
Show propertiesHide properties
objectplatformstringWhich of the person's accounts this grant landed on.
twitchkickplatform_user_idstringsourcestringWhat earned the credits. manual covers both dashboard and API grants.
sub_tier1sub_tier2sub_tier3gift_submanualcreditsintegerCredits in this grant.
credits_usedintegerHow many of them were spent.
awarded_atstring<date-time>usageobjectrequiredSub-reward messages; spent credits are credits.used.
Show propertiesHide properties
queuedintegerSub-reward messages waiting in the TTS queue right now.
playedintegerSub-reward messages that played on stream.
last_used_atstring<date-time> | nullMissing or invalid credential (missing_api_key / invalid_api_key, or invalid_token for an expired/revoked OAuth access token).
errorstringrequiredHuman-readable message.
codestringMachine-readable code (e.g. missing_scope, not_in_queue).
The key lacks the required scope (missing_scope).
errorstringrequiredHuman-readable message.
codestringMachine-readable code (e.g. missing_scope, not_in_queue).
required_scopestringNo Twitch or Kick account matches (user_not_found), or the channel isn't connected to that platform.
errorstringrequiredHuman-readable message.
codestringMachine-readable code (e.g. missing_scope, not_in_queue).
More than one signed-in viewer matches (ambiguous_viewer) - two people share that name, or a bare id exists on both platforms. Retry with <platform>:<id>.
errorstringrequiredHuman-readable message.
codestringMachine-readable code (e.g. missing_scope, not_in_queue).
Rate limit exceeded - check the RateLimit-* headers.
errorstring