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

A viewer's sub-reward history

The viewer’s played sub-reward messages, most recent first - the same shape as /tts/history, filtered to this viewer’s sub rewards. Replays by the streamer are excluded; a sub reward still waiting to play shows up in /tts/queue like any other tip. Requires viewers:read.

GET/viewers/{user}/rewards
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.
Query parameters
limitinteger
min 1 · max 100 · default: 25
beforestring
Cursor - an `order_id` from a previous page (`next_cursor`). Returns rows strictly older than it.
Responses
200One page of played sub rewards.
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).
rewardsHistoryTip[]
Show properties
Array of HistoryTip
order_idstring
namestring
amountnumber | null
messagestring | null
tts_urlstring<uri> | null
is_replayboolean
is_sub_rewardboolean
twitch_user_idstring | null
name_was_filteredboolean
message_was_filteredboolean
queued_atstring<date-time>
When the tip entered the queue.
played_atstring<date-time>
When it finished playing on stream.
has_moreboolean
next_cursorstring | null
400Unknown `before` cursor (`bad_cursor`).
errorstringrequired
Human-readable message.
codestring
Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
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/rewards" \
  -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"
  },
  "rewards": [
    {
      "order_id": "string",
      "name": "string",
      "amount": 0,
      "message": "string",
      "tts_url": "http://example.com",
      "is_replay": true,
      "is_sub_reward": true,
      "twitch_user_id": "string",
      "name_was_filtered": true,
      "message_was_filtered": true,
      "queued_at": "2019-08-24T14:15:22Z",
      "played_at": "2019-08-24T14:15:22Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}