Skip to content
TipPage Docs
Esc
↑↓navigate↵open⌘Jpreview

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.

GET/viewers/{user}
Authorization
AuthorizationBearer token (tp_live_... or tpat_...) · headerrequired

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

Path parameters
userstringrequired

twitch:<id or login>, kick:<id or login>, v_..., or a bare id or login (see above).

Responses
200

The viewer.

viewerViewerPersonrequired

The 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 properties
idstring | nullrequired

TipPage'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_inbooleanrequired

Whether any account of theirs has signed in to THIS tip page.

signed_in_withstring | nullrequired

The platform of their most recent sign-in here.

Allowed:twitchkicknull
display_namestring | nullrequired
profile_image_urlstring<uri> | nullrequired
first_signed_in_atstring<date-time> | nullrequired

Their first sign-in to this tip page, on any account.

last_active_atstring<date-time> | nullrequired

Last account activity seen here (profile refreshes included).

platformsobjectrequired

The person's account per platform, with its standing on this channel there. null = no known account on that platform.

Show properties
twitchViewerPlatform | nullrequired
Show properties
One of:
ViewerPlatform
idstringrequired

The platform's user id.

loginstring | nullrequired
display_namestring | nullrequired
profile_image_urlstring<uri> | nullrequired
signed_inbooleanrequired

Whether THIS account has signed in to the tip page.

followingboolean | nullrequired
followed_atstring<date-time> | nullrequired
subscribedboolean | nullrequired

Read live; when the live read fails on an account that signed in here, the tier the sign-in recorded stands in.

tierinteger | nullrequired

Current sub tier (Kick has no tiers - always 1).

Allowed:123null
giftedboolean | nullrequired

Twitch only - the current sub is a gift.

gifter_loginstring | nullrequired
sub_monthsinteger | nullrequired

Cumulative sub months as last seen (see the operation).

sub_months_atstring<date-time> | nullrequired

When sub_months was seen.

sub_months_sourcestring | nullrequired

chat = their subscriber badge in chat, resub = a shared resub, kick = read from Kick.

Allowed:chatresubkicknull
moderatorboolean | nullrequired

A moderator of this channel on that platform.

vipboolean | nullrequired

A VIP of this channel on that platform.

chatobjectrequired
Show properties
messagesinteger

Chat messages counted on this channel from this account.

first_seenstring<date> | null

First day they chatted.

last_seen_atstring<date-time> | null
null
null
kickViewerPlatform | nullrequired
Show properties
One of:
ViewerPlatform
idstringrequired

The platform's user id.

loginstring | nullrequired
display_namestring | nullrequired
profile_image_urlstring<uri> | nullrequired
signed_inbooleanrequired

Whether THIS account has signed in to the tip page.

followingboolean | nullrequired
followed_atstring<date-time> | nullrequired
subscribedboolean | nullrequired

Read live; when the live read fails on an account that signed in here, the tier the sign-in recorded stands in.

tierinteger | nullrequired

Current sub tier (Kick has no tiers - always 1).

Allowed:123null
giftedboolean | nullrequired

Twitch only - the current sub is a gift.

gifter_loginstring | nullrequired
sub_monthsinteger | nullrequired

Cumulative sub months as last seen (see the operation).

sub_months_atstring<date-time> | nullrequired

When sub_months was seen.

sub_months_sourcestring | nullrequired

chat = their subscriber badge in chat, resub = a shared resub, kick = read from Kick.

Allowed:chatresubkicknull
moderatorboolean | nullrequired

A moderator of this channel on that platform.

vipboolean | nullrequired

A VIP of this channel on that platform.

chatobjectrequired
Show properties
messagesinteger

Chat messages counted on this channel from this account.

first_seenstring<date> | null

First day they chatted.

last_seen_atstring<date-time> | null
null
null
creditsobjectrequired
Show properties
availableinteger

Credits spendable right now.

totalinteger

Credits ever granted.

usedinteger

Credits already spent.

pendinginteger

Gift-sub credits waiting for their first sign-in to convert (informational - already part of neither total nor available).

grantsobject[]required

The award ledger, newest first (up to 100 rows).

Show properties
Array of object
platformstring

Which of the person's accounts this grant landed on.

Allowed:twitchkick
platform_user_idstring
sourcestring

What earned the credits. manual covers both dashboard and API grants.

Allowed:sub_tier1sub_tier2sub_tier3gift_submanual
creditsinteger

Credits in this grant.

credits_usedinteger

How many of them were spent.

awarded_atstring<date-time>
usageobjectrequired

Sub-reward messages; spent credits are credits.used.

Show properties
queuedinteger

Sub-reward messages waiting in the TTS queue right now.

playedinteger

Sub-reward messages that played on stream.

last_used_atstring<date-time> | null
401

Missing or invalid credential (missing_api_key / invalid_api_key, or invalid_token for an expired/revoked OAuth access token).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

403

The key lacks the required scope (missing_scope).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

required_scopestring
404

No Twitch or Kick account matches (user_not_found), or the channel isn't connected to that platform.

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

409

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

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. missing_scope, not_in_queue).

429

Rate limit exceeded - check the RateLimit-* headers.

errorstring
Try it
Server
Authorization
Parameters
Request
curl -X GET 'https://api.tippage.com/v1/viewers/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
Response
{
  "viewer": {
    "id": "v_9f3c1a7e42b08d61",
    "signed_in": true,
    "signed_in_with": "twitch",
    "display_name": "GigaChad42",
    "profile_image_url": "http://example.com",
    "first_signed_in_at": "2019-08-24T14:15:22Z",
    "last_active_at": "2019-08-24T14:15:22Z"
  },
  "platforms": {
    "twitch": {
      "id": "123456789",
      "login": "gigachad42",
      "display_name": "GigaChad42",
      "profile_image_url": "http://example.com",
      "signed_in": true,
      "following": true,
      "followed_at": "2019-08-24T14:15:22Z",
      "subscribed": true,
      "tier": 1,
      "gifted": true,
      "gifter_login": "string",
      "sub_months": 0,
      "sub_months_at": "2019-08-24T14:15:22Z",
      "sub_months_source": "chat",
      "moderator": true,
      "vip": true,
      "chat": {
        "messages": 0,
        "first_seen": "2019-08-24",
        "last_seen_at": "2019-08-24T14:15:22Z"
      }
    },
    "kick": {
      "id": "123456789",
      "login": "gigachad42",
      "display_name": "GigaChad42",
      "profile_image_url": "http://example.com",
      "signed_in": true,
      "following": true,
      "followed_at": "2019-08-24T14:15:22Z",
      "subscribed": true,
      "tier": 1,
      "gifted": true,
      "gifter_login": "string",
      "sub_months": 0,
      "sub_months_at": "2019-08-24T14:15:22Z",
      "sub_months_source": "chat",
      "moderator": true,
      "vip": true,
      "chat": {
        "messages": 0,
        "first_seen": "2019-08-24",
        "last_seen_at": "2019-08-24T14:15:22Z"
      }
    }
  },
  "credits": {
    "available": 0,
    "total": 0,
    "used": 0,
    "pending": 0
  },
  "grants": [
    {
      "platform": "twitch",
      "platform_user_id": "string",
      "source": "sub_tier1",
      "credits": 0,
      "credits_used": 0,
      "awarded_at": "2019-08-24T14:15:22Z"
    }
  ],
  "usage": {
    "queued": 0,
    "played": 0,
    "last_used_at": "2019-08-24T14:15:22Z"
  }
}