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

200The 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 | anyrequired

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

any

any

kickViewerPlatform | anyrequired

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

any

any

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

401Missing 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`).

403The key lacks the required scope (`missing_scope`).

errorstringrequired

Human-readable message.

codestring

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

required_scopestring

404No 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`).

409More 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`).

429Rate limit exceeded - check the `RateLimit-*` headers.

errorstring

Request

curl -X GET "https://api.tippage.com/v1/viewers/string" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.tippage.com/v1/viewers/string", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "https://api.tippage.com/v1/viewers/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

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"
  }
}