---
search:
  tags:
    - Viewers
    - GET
seo:
  description: >-
    One person and their standing on this channel, per platform account - signed
    in… Reference for the GET /viewers/{user} endpoint in the TipPage Developer
    API.
sidebar:
  label: Look up any viewer
  badge: GET
title: Look up any viewer
type: openapi-operation
---
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}`

**Responses**

- `200` — The viewer.
- `401` — Missing or invalid credential (\`missing\_api\_key\` / \`invalid\_api\_key\`, or \`invalid\_token\` for an expired/revoked OAuth access token).
- `403` — The key lacks the required scope (\`missing\_scope\`).
- `404` — No Twitch or Kick account matches (\`user\_not\_found\`), or the channel isn't connected to that platform.
- `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\>\`.
- `429` — Rate limit exceeded - check the \`RateLimit-\*\` headers.

Response example, 200:

```json
{
  "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"
  }
}
```
