One viewer in full

A single viewer: profile, when they first signed in, their credit balance (including gift-sub credits still pending because they arrived before the first sign-in), the full grant ledger, and sub-reward usage totals. Requires viewers:read.

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

Which viewer: `<platform>:<id>` (`twitch:123456789`, `kick:123`), a bare numeric id, or a login / display name (case-insensitive, matched on both platforms; URL-encode names with special characters). A bare id is tried on Twitch then Kick - if an account with that id has signed in on both, the answer is `409 ambiguous_viewer`; a name shared by two different people is 409 too, while a name that matches both of ONE person's linked accounts resolves to the one they signed in with most recently. Prefer `platform:id` in automation - it survives renames and can never be ambiguous.

Responses

200The viewer.

viewerViewer

A viewer who has signed in to the tip page. `platform` + `platform_user_id` name the account they signed in with here; `linked_accounts` lists the person's other platform account(s), if they linked any (may be empty). Credits and reward history are read across the whole set.

Show properties

platformstringrequired

Allowed:twitchkick

platform_user_idstringrequired

loginstring | null

display_namestring | null

profile_image_urlstring<uri> | null

subscriber_tierinteger

Their sub tier as last seen (0 = not subscribed).

Allowed:0123

first_signed_in_atstring<date-time>

When they first signed in to this tip page.

last_active_atstring<date-time>

Last account activity seen (profile refreshes included).

linked_accountsobject[]required

The person's OTHER platform accounts - never the one above. Empty when nothing is linked.

Show properties

Array of object

platformstring

Allowed:twitchkick

platform_user_idstring

loginstring | null

display_namestring | null

creditsobject

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[]

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>

usageobject

Show properties

total_usedinteger

Credits spent

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 viewer with that name or id has ever signed in to this tip page (`viewer_not_signed_in`). Signing in on the tip page (Twitch or Kick) is what creates a viewer - until then they can't be looked up or granted credits.

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": {
    "platform": "twitch",
    "platform_user_id": "123456789",
    "login": "gigachad42",
    "display_name": "GigaChad42",
    "profile_image_url": "http://example.com",
    "subscriber_tier": 0,
    "first_signed_in_at": "2019-08-24T14:15:22Z",
    "last_active_at": "2019-08-24T14:15:22Z",
    "linked_accounts": [
      {
        "platform": "twitch",
        "platform_user_id": "string",
        "login": "string",
        "display_name": "string"
      }
    ]
  },
  "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": {
    "total_used": 0,
    "queued": 0,
    "played": 0,
    "last_used_at": "2019-08-24T14:15:22Z"
  }
}