Twitch Schedule API. Upcoming streams, page by page.

Upcoming streams a channel has announced. We handle the proxies, blocks and platform changes.

Returns the streams a public Twitch channel has scheduled and not yet started, soonest first, from its login, link or numeric ID. Each slot has its title, category, start and end time, whether it was cancelled and how often it repeats, with the channel's numeric ID, login, name and Partner badge. Each page covers a week.

GET /v1/twitch/schedule

Read the API reference

1 credit per page, $0.75–$1.97 per 1,000 pages
17 typed fields null when unknown
50 upcoming streams per page, soonest first, a week per page
handle is all it needs, e.g. riotgames

Send one request. Get up to 50 upcoming streams back.

Copy the request in your language, or hand it to your agent. Sign up for an API key and your first 100 credits are free.

$ npm install socialtap

handle = riotgames

Open in playground

GET /v1/twitch/scheduleTry in

const params = new URLSearchParams({
  handle: "riotgames",
});
const res = await fetch(`https://socialtap.dev/v1/twitch/schedule?${params}`, {
  headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { data, page, meta } = body;
console.log(data, meta.credits_charged);

import os

import requests

res = requests.get(
    "https://socialtap.dev/v1/twitch/schedule",
    params={"handle": "riotgames"},
    headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data, page, meta = body["data"], body["page"], body["meta"]
print(data, meta["credits_charged"])

require "json"
require "net/http"

uri = URI("https://socialtap.dev/v1/twitch/schedule")
uri.query = URI.encode_www_form('handle' => 'riotgames')
req = Net::HTTP::Get.new(uri)
req["x-api-key"] = ENV.fetch("SOCIALTAP_API_KEY")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
body = JSON.parse(res.body)
raise "#{body["error"]["code"]}: #{body["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
pp body["data"]
puts body["meta"]["credits_charged"]

<?php

$query = http_build_query([
    'handle' => 'riotgames',
]);
$ch = curl_init('https://socialtap.dev/v1/twitch/schedule?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['x-api-key: ' . getenv('SOCIALTAP_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) >= 400) {
    throw new RuntimeException($body['error']['code'] . ': ' . $body['error']['message']);
}
print_r($body['data']);
echo $body['meta']['credits_charged'], PHP_EOL;

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
)

func main() {
	q := url.Values{}
	q.Set("handle", "riotgames")
	req, err := http.NewRequest("GET", "https://socialtap.dev/v1/twitch/schedule?"+q.Encode(), nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	var body struct {
		Data  json.RawMessage `json:"data"`
		Page  json.RawMessage `json:"page"`
		Meta  map[string]any  `json:"meta"`
		Error *struct {
			Code    string `json:"code"`
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		log.Fatal(err)
	}
	if body.Error != nil {
		log.Fatalf("%s: %s", body.Error.Code, body.Error.Message)
	}
	fmt.Println(string(body.Data), body.Meta["credits_charged"])
}

curl 'https://socialtap.dev/v1/twitch/schedule?handle=riotgames' \
  -H "x-api-key: $SOCIALTAP_API_KEY"

{
  "data": [
    {
      "approximate_fields": [],
      "category": "League of Legends",
      "ended_at": null,
      "host": {
        "avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/35b02a12-d516-499e-90f8-7899f136fa18-profile_image-300x300.png",
        "display_name": "Riot Games",
        "id": "36029255",
        "is_verified": true,
        "url": "https://www.twitch.tv/riotgames",
        "username": "riotgames"
      },
      "id": "eyJzZWdtZW50SUQiOiJiYmQ2OGYxOC03MTYwLTRjYjgtODdmOC1mY2Y1NDZiN2FmMjYiLCJpc29ZZWFyIjoyMDI2LCJpc29XZWVrIjo0NX0=",
      "metrics": {
        "concurrent_viewer_count": null,
        "like_count": null,
        "view_count": null
      },
      "platform": "twitch",
      "platform_specific": {
        "twitch": {
          "base_segment_id": "bbd68f18-7160-4cb8-87f8-fcf546b7af26",
          "cancellation_ends_at": null,
          "categories": [
            {
              "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/21779-285x380.jpg",
              "id": "21779",
              "name": "League of Legends",
              "slug": "league-of-legends"
            }
          ],
          "is_cancelled": false,
          "repeat_ends_after_count": 1,
          "scheduled_end_at": "2026-11-06T06:30:00Z",
          "vacation": null
        }
      },
      "post_id": null,
      "scheduled_start_at": "2026-11-05T20:30:00Z",
      "started_at": null,
      "status": "scheduled",
      "streams": [],
      "text": null,
      "thumbnail_url": null,
      "title": "Worlds 2026 | Knockout Stage Day 3",
      "unknown_fields": [],
      "url": "https://www.twitch.tv/riotgames/schedule"
    },
    {
      "approximate_fields": [],
      "category": "League of Legends",
      "ended_at": null,
      "host": {
        "avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/35b02a12-d516-499e-90f8-7899f136fa18-profile_image-300x300.png",
        "display_name": "Riot Games",
        "id": "36029255",
        "is_verified": true,
        "url": "https://www.twitch.tv/riotgames",
        "username": "riotgames"
      },
      "id": "eyJzZWdtZW50SUQiOiI0NDExNTQwOC1iZDYyLTRkZjktOTVmYy1iYTRiNzFjM2NhMDYiLCJpc29ZZWFyIjoyMDI2LCJpc29XZWVrIjo0NX0=",
      "metrics": {
        "concurrent_viewer_count": null,
        "like_count": null,
        "view_count": null
      },
      "platform": "twitch",
      "platform_specific": {
        "twitch": {
          "base_segment_id": "44115408-bd62-4df9-95fc-ba4b71c3ca06",
          "cancellation_ends_at": null,
          "categories": [
            {
              "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/21779-285x380.jpg",
              "id": "21779",
              "name": "League of Legends",
              "slug": "league-of-legends"
            }
          ],
          "is_cancelled": false,
          "repeat_ends_after_count": 1,
          "scheduled_end_at": "2026-11-07T06:30:00Z",
          "vacation": null
        }
      },
      "post_id": null,
      "scheduled_start_at": "2026-11-06T20:30:00Z",
      "started_at": null,
      "status": "scheduled",
      "streams": [],
      "text": null,
      "thumbnail_url": null,
      "title": "Worlds 2026 | Knockout Stage Day 4",
      "unknown_fields": [],
      "url": "https://www.twitch.tv/riotgames/schedule"
    },
    {
      "approximate_fields": [],
      "category": "League of Legends",
      "ended_at": null,
      "host": {
        "avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/35b02a12-d516-499e-90f8-7899f136fa18-profile_image-300x300.png",
        "display_name": "Riot Games",
        "id": "36029255",
        "is_verified": true,
        "url": "https://www.twitch.tv/riotgames",
        "username": "riotgames"
      },
      "id": "eyJzZWdtZW50SUQiOiI4MDAzOGYzMC04Y2QzLTQ5ZGYtODhjYi1kMmJkZmViYWQ0MGUiLCJpc29ZZWFyIjoyMDI2LCJpc29XZWVrIjo0NX0=",
      "metrics": {
        "concurrent_viewer_count": null,
        "like_count": null,
        "view_count": null
      },
      "platform": "twitch",
      "platform_specific": {
        "twitch": {
          "base_segment_id": "80038f30-8cd3-49df-88cb-d2bdfebad40e",
          "cancellation_ends_at": null,
          "categories": [
            {
              "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/21779-285x380.jpg",
              "id": "21779",
              "name": "League of Legends",
              "slug": "league-of-legends"
            }
          ],
          "is_cancelled": false,
          "repeat_ends_after_count": 1,
          "scheduled_end_at": "2026-11-08T06:30:00Z",
          "vacation": null
        }
      },
      "post_id": null,
      "scheduled_start_at": "2026-11-07T20:30:00Z",
      "started_at": null,
      "status": "scheduled",
      "streams": [],
      "text": null,
      "thumbnail_url": null,
      "title": "Worlds 2026 | Knockout Stage Day 5",
      "unknown_fields": [],
      "url": "https://www.twitch.tv/riotgames/schedule"
    }
  ],
  "page": {
    "has_more": true,
    "next_cursor": "c1.EXAMPLE_CURSOR",
    "next_cursor_expires_at": "2026-10-26T12:00:00Z",
    "end_reason": null
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "twitch",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 287,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": {
      "kind": "profile",
      "id": "36029255",
      "url": "https://www.twitch.tv/riotgames"
    },
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}

import { SocialTap } from "socialtap";

const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY

const res = await client.twitch.schedule.list({ handle: "riotgames" });
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class Main {
    public static void main(String[] args) throws Exception {
        String query = "handle=" + encode("riotgames");
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://socialtap.dev/v1/twitch/schedule?" + query))
            .header("x-api-key", System.getenv("SOCIALTAP_API_KEY"))
            .GET()
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        // An error is {"error": {"code", "message", ...}}; success is {data, meta}, meta.credits_charged its price.
        if (response.statusCode() >= 400) throw new RuntimeException(response.body());
        System.out.println(response.body());
    }

    static String encode(String value) {
        return URLEncoder.encode(value, StandardCharsets.UTF_8);
    }
}

using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("SOCIALTAP_API_KEY"));

var query = string.Join("&",
    "handle=" + Uri.EscapeDataString("riotgames"));
var res = await http.GetAsync("https://socialtap.dev/v1/twitch/schedule?" + query);
using var body = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
if (!res.IsSuccessStatusCode)
{
    var error = body.RootElement.GetProperty("error");
    throw new Exception($"{error.GetProperty("code")}: {error.GetProperty("message")}");
}
Console.WriteLine(body.RootElement.GetProperty("data"));
Console.WriteLine(body.RootElement.GetProperty("meta").GetProperty("credits_charged"));

// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
use std::env;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let res = reqwest::blocking::Client::new()
        .get("https://socialtap.dev/v1/twitch/schedule")
        .query(&[("handle", "riotgames")])
        .header("x-api-key", env::var("SOCIALTAP_API_KEY")?)
        .send()?;
    let ok = res.status().is_success();
    let body: serde_json::Value = res.json()?;
    if !ok {
        return Err(format!("{}: {}", body["error"]["code"], body["error"]["message"]).into());
    }
    println!("{} {}", body["data"], body["meta"]["credits_charged"]);
    Ok(())
}

200 OK · GET https://socialtap.dev/v1/twitch/scheduleLong arrays and strings are shortened here. Real responses are complete.Docs

One schema on 2 platforms.

The response reference lists every field, its type and when it is null. See the full schema.

Null means unknown
A field Twitch doesn't show is null, never zero or an empty string, so a real zero always means zero.
What it accepts
The Twitch channel: its login with or without the @ (riotgames), a channel link (twitch.tv/riotgames/schedule), or its numeric ID (36029255).
Write one parser
Twitch and TikTok answer in these fields, so the code that reads one reads them all.

platformstring: Platform ID (tiktok, youtube, …).
idstring: Platform-native ID of the broadcast (string; TikTok room ID, YouTube video ID).
urlstring: Public page of the broadcast (TikTok: the host's LIVE page, tiktok.com/@<username>/live).
statusstring: live: on air now; scheduled: announced, not started; ended: over. New values may be added; treat an unknown value as not live.
titlestring: The broadcast's title as the host set it.
textstring: Description as plain text; null where the platform has none.
categorystring: The topic or game the broadcast is filed under, as the platform names it.
hostobject: The broadcasting account.

What teams build with the Twitch Schedule API.

Know when a streamer goes live next
Build a calendar of a community's channels
Plan sponsorships around announced streams
Track what an esports league schedules and cancels

Good to know before you build.

A slot leaves the list when it starts, and Twitch doesn't say whether it aired. For what is on air now, use the Twitch Profile API.
A cancelled slot stays on the list with status scheduled and platform_specific.twitch.is_cancelled true, as Twitch's schedule keeps it.
A walk covers twelve weeks. A weekly slot repeats with no end and a one-off can sit further out, so a walk that gets there ends with page.end_reason platform_limit, unless Twitch says nothing is left.
A channel that set no schedule returns an empty list. A channel Twitch has suspended or taken down returns private_or_unavailable, and a name nobody holds, or a channel its owner closed, not_found.
A bare number is read as an account's ID. A login can also be all digits: write it with its @ (@12345) or send its link.

1 credit per page. Failed requests are free.

Buy credits once and spend them on any endpoint, on any platform.

Plans and packs How this endpoint is priced How credits work

Source	Price per successful page	Per 1,000 pages
Platform API `api`	1 credit	$0.75–$1.97

Cache hits are free.
Credits from packs and top-ups never expire.
A monthly plan's credits are spent first, and what is left of them ends at each renewal.
Prices exclude tax: sales tax is added at checkout where it applies.
Outside the US, plans and packs are sold to businesses: checkout asks for your VAT, GST or other business tax ID.

Questions about the Twitch Schedule API.

Try it on an account you know.

Paste its handle or link in the playground, or copy the request into your code.

free credits

No credit card
Failed requests are free
Works on all 218 endpoints

Start for free Read the docs

Twitch Schedule API. Upcoming streams, page by page.

Twitch Schedule API at a glance

Send one request. Get up to 50 upcoming streams back.

One schema on 2 platforms.

Null means unknown

What it accepts

Write one parser

What teams build with the Twitch Schedule API.

Know when a streamer goes live next

Build a calendar of a community's channels

Plan sponsorships around announced streams

Track what an esports league schedules and cancels

Good to know before you build.

1 credit per page. Failed requests are free.

Questions about the Twitch Schedule API.

Livestreams on 1 more platform.

Twitch API. 5 endpoints, one key.

Try it on an account you know.