Upcoming Changes to the Streams v5 Endpoints

Starting on or soon after February 20, 2020, we are making a few changes to Streams v5 endpoints.

  1. The stream endpoint will no longer return a _total count field
  2. offset parameter with a value over 900 will be ignored

All third party application developers who are actively using this functionality are encouraged to update their applications to remove dependencies on these features by February 20 to ensure that they continue to function as expected. The limitation on total and offset can be handled by migrating to Helix.

We currently do not have plans to introduce new features to replicate this functionality.

Please let us know if you have any questions or feedback in the comments below.

What’s changing?

The “Get Live Streams” and “Get Followed Streams” v5 endpoints will no longer return a _total count field in the response. We recommend migrating to Helix to retrieve the total count.

The “Get Live Streams” v5 endpoint will no longer accept an offset value greater than 900. If the value of offset is greater than 900, the offset parameter will be ignored and the API request will proceed as if the value was not provided.

The counts provided by “Get Streams Summary” are not affected by this change.

Who will be impacted by these changes?

Any third party developer using v5 Streams endpoints who is reading _total from the return payload, or using the offset query parameter.

Why are we making these changes?

We introduced a new internal service that powers our discovery experience and these changes are necessary to reduce latency across Twitch for all users.

When do these changes take effect?

Starting on or soon after February 20, 2020.

If I’m reading this correctly, the changes to the offset parameter have the potential to be pretty serious for integrations such as mine, as there several properties missing in Helix which are rather fundamental. For example, it’s not possible to efficiently get multiple channels follower counts in helix.

Even if these where added right now, the timeframe to make these changes is super short. It would be possible to use Helix for most of the data and then go back to v5 for the missing parts, but again the time to make these changes is tiny.

This has me a wee bit concerned…

3 Likes

Hi just wondering if we can get an updated timeline on when this is due tol roll out. You say “on or soon after” the 20th which ofcourse is today and this affects a core service I maintain.
Thanks

Assuming this went into effect a couple hours ago?

Yes. This change went live already.

Not sure if an email was supposed to go out regarding this change, but I never received one.

You suggest migrating to Helix, but the newest Twitch API has yet to implement “Get Followed Streams”. Still waiting on that.

2 Likes

Yeah, a little confused because I thought Twitch committed to feature parity before forcing people off kraken - like a week ago, but I guess that only applied to rate limiting.

3 Likes

Please add your recommendation for “Get Followed Streams” to the developer UserVoice forum. We have more Helix endpoints on the way and will be started a closed beta program soon before launching them publicly.

These changes are the result of an updated internal service as briefly mentioned above. Unfortunately, this meant the changes were not something we could pause like the v5 rate limits.

Whatever the reasons for these changes were, you also introduced a bug related to the offset and limit parameters. See this:

offset=0, limit=12

$ curl -s \
  -H "Accept: application/vnd.twitchtv.v5+json" \
  -H "Client-ID: YOUR_CLIENT_ID" \
  "https://api.twitch.tv/kraken/streams?offset=0&limit=12" \
  | jq "[.streams[]] | length"
12

offset=12, limit=12

$ curl -s \
  -H "Accept: application/vnd.twitchtv.v5+json" \
  -H "Client-ID: YOUR_CLIENT_ID" \
  "https://api.twitch.tv/kraken/streams?offset=12&limit=12" \
  | jq "[.streams[]] | length"
11

As you can see, setting an offset greater than 0 makes the API response lack one item.

This API bug is currently breaking my application, because its infinite scroll mechanism has a fallback for when the _total metadata is/was missing (as it was inconsistent before), and it expects the number of results of the API response to be equal to the requested limit. If fewer records are returned than requested, it treats this as the end of the available records.

I know that this could be implemented differently and another query could be made and then checked if there are no records in the response, but that’s one additional and unnecessary API request, especially considering API rate-limiting on helix once I made the switch. The API bug is also annoying, because my infinite scroll implementation has a calculation for how many records are needed in order to fill the route’s page with just one query, and having one item missing from the API response breaks this as well.

Could you please take a look at this bug? Other endpoints than /streams are also affected by this, eg /games/top (offset=12, limit=12).
Thanks.

edit:
And also the language parameter bug, in case you haven’t seen my post from yesterday on the API forums section yet:

Thanks for reporting this bug, although I cannot replicate the issue. Calling your examples both result in 12 for me and testing other calls with various offsets and limits results in the expected limit. Please let me know if the issue still occurs for your tests. In the meantime, I’ll share this with the team to double check this behavior. I’ll also share the language post.

For future reference, you can always file bugs using our GitHub repo for bug reporting at github.com/twitchdev/issues.

This report is on https://github.com/twitchdev/issues/issues/67

I also noticed that the language issue was reported on https://github.com/twitchdev/issues/issues/66

I have made my recommendation to that forum and it was replied and closed by an admin saying you need to get that functionality through the Webhook interface now.

My application that uses the Twitch API is a desktop application with NO support to act as a server for callbacks. It would really be unfortunate if Twitch does not decide to move this endpoint into Helix.

You also need to be aware of this change: Requiring OAuth for Helix Twitch API Endpoints

The “Get Followed Streams” requires OAuth already, so all my users of my application already do generate a access token. That is not a problem.

The problem is moving this endpoints functionality to Webhook only where Webhooks are designed to have a registered URL as a callback, thus designed for web apps, NOT desktop apps.

It would appear that the Recommendation you made was closed as the person closing it misunderstood your request.

I did leave a comment on the closed thread. Hopefully the person see’s its, otherwise I’ll probably just create a new request and make sure to make it known that Webhooks were not meant for desktop apps.

Anyway to wander off topic, for your paticular use case:

Call: https://dev.twitch.tv/docs/api/reference#get-users-follows to get all the people you follow then call https://dev.twitch.tv/docs/api/reference#get-streams 100 users at a time. I don’t expect Twitch to add the “get followed streams” end point to helix it’s solved with a few requests to Helix.