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

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_...) · headerrequired
A TipPage API key, created in Dashboard → Settings → Developer.
Path parameters
userstringrequired
The viewer's Twitch user id, login, or display name (names are case-insensitive; URL-encode names with special characters). All-digit input is tried as a user id first. Prefer the user 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 with Twitch.
Show properties
twitch_user_idstring
loginstring
display_namestring
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).
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
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 API key (`missing_api_key` / `invalid_api_key`).
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 Twitch user id has ever signed in to this tip page (`viewer_not_signed_in`). Signing in with Twitch 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 that name (`ambiguous_viewer`) - retry with the Twitch user 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"
Response
{
  "viewer": {
    "twitch_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"
  },
  "credits": {
    "available": 0,
    "total": 0,
    "used": 0,
    "pending": 0
  },
  "grants": [
    {
      "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"
  }
}