🕙Stream audience viewtime [NEW]

The Stream Viewtime endpoint provides per-viewer cumulative watch time for a specific Twitch broadcast. Use it to identify and reward your most engaged authenticated viewers during a stream, power loyalty programs and raffles, generate sponsor-ready engagement reports, and inform real-time community operations (e.g., VIP shout‑outs).

To obtain a list of authorized viewers for a specific channel's broadcast, that channel must be authorized on Streams Charts via Twitch.

Available platforms

One request will provide you with data for specific stream of a specific channel. Since viewer watchtime is available only for Twitch channels, use the filter platform=twitch to get it.

How to access stream audience viewtime set of metrics

You will need a Client ID and a token to use Streams Charts API. Your Client ID is bound to your account and can never be changed, but you can change your access token anytime for security reasons.

To get a specific set of metrics by one stream of a specific channel, use the following route: /api/jazz/channels/{name}/streams-extra/{stream-id}/viewtime?platform=twitch

To get stream id(s) of specific channel, use single channel stats endpoint.

To see how it works for a single stream of a specific channel, use the example request below.

curl -X GET https://streamscharts.com/api/jazz/channels/jinnytty/streams-extra/314517368915/viewtime?platform=twitch \
-H 'Client-ID: XXXXXXXXXXXX' \
-H 'Token: YYYYYYYYYYYYYY'

Use your Client ID and token instead of "XXXXXXXXXXXX" and "YYYYYYYYYYYYYY", which you can find here.

The response you would get would be a JSON response that contains something like a sample response:

{
"data":{
"platform": "twitch",
"channel_name": "jinnytty",
"channel_display_name": "Jinnytty",
"channel_id": "159498717",
"avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/37567ea1-8246-4385-bcf6-8a3cdb9ca93b-profile_image-300x300.png",
"stream_id": "314517368915",
"stream_status": "🇨🇳 CHONGQING : APPARENTLY THERES SOME EPIC DRONE SHOW ? | !vods for past streams  | @Jinnytty !socials !vod !subtember",
"stream_start": "2025-10-02 10:21:10",
"stream_end": "2025-10-02 14:25:00",
"stream_live": "no",
"stream_language": "en",
"total_auth_viewers": 12557,
"snapshot_at": "2025-10-02 14:20:00",
"page": 1,
"viewers_by_viewtime":[
{
"username": "impalatv",
"view_duration_m": "240"
},
{
"username": "tarz",
"view_duration_m": "240"
},
...
]
}
}

Description

Returns per-viewer cumulative watch time for a specific Twitch stream, along with stream and channel metadata.

The stream_live flag indicates whether the stream is live at the exact time of the request. Use snapshot_at to understand which timestamp you requested. For live streams, viewer watch time aggregates are refreshed in 5‑minute intervals. Requests made within the same 5‑minute interval return identical viewtime values; once the next 5‑minute interval is processed, values update accordingly.

Pagination is available for the viewers_by_viewtime list. Each page returns up to 50,000 authorized viewers sorted by their cumulative viewtime. The total_auth_viewers and page fields help clients navigate large audiences efficiently and compute total pages.

Pagination

• The viewers_by_viewtime array is paginated.

• Page size: up to 50,000 authorized viewers per page.

• Use the page query parameter to navigate: page=1 (default), page=2, etc.

Example with pagination query: curl -X GET "https://streamscharts.com/api/jazz/channels/caedrel/streams-extra/315218933338/viewtime?platform=twitch&page=2"

Billing

• 125 credits per unique stream per account per day (“per day” means within a 24-hour day aligned to your account’s billing day; repeated calls to the same stream in that period are free).

• If you repeat the same request (same channel and same stream-id) within the same calendar day, you are not charged again.

• If you request a different stream (different stream-id), even for the same channel, a new 125‑credit charge applies.

Example use cases

• Reward programs and loyalty tiers: Identify top engaged authenticated viewers by cumulative watch time during a broadcast to grant badges, tiered rewards, or raffle eligibility.

• Sponsor/partner reporting: Quantify time‑spent distribution among authenticated viewers for specific sponsored streams.

• Moderation/community ops: Detect highly engaged community members in real time for shout‑outs or VIP consideration.

• A/B programming: Compare watch time retention across segments within the same stream by polling at 5‑minute boundaries.

Check Streams Charts Viewer Rewards Deck, a special solution to reward and increase steady viewership.