Clips Reference

While you can migrate from v3 to v5, know that v5 is deprecated and will be shutdown in the future. We prefer that you migrated directly to the new Twitch API.

Endpoint	Description
Get Clip	Gets details about a specified clip. Clips are referenced by a globally unique string called a slug.
Get Top Clips	Gets the top clips which meet a specified set of parameters.
Get Followed Clips	Gets the top clips for the games followed by a specified user.

Get Clip

✎

Gets details about a specified clip. Clips are referenced by a globally unique string called a slug.

Authentication

None

URL

GET https://api.twitch.tv/kraken/clips/

Optional Query String Parameters

None

Example Request

This gets the clip referenced by the slug AmazonianEncouragingLyrebirdAllenHuhu.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/clips/AmazonianEncouragingLyrebirdAllenHuhu'

Example Response

{
  "slug": "AmazonianEncouragingLyrebirdAllenHuhu",
  "tracking_id": "13160765",
  "url": "https://clips.twitch.tv/AmazonianEncouragingLyrebirdAllenHuhu?tt_medium=clips_api&tt_content=url",
  "embed_url": "https://clips.twitch.tv/embed?clip=AmazonianEncouragingLyrebirdAllenHuhu&tt_medium=clips_api&tt_content=embed",
  "embed_html": "",
  "broadcaster": {
    "id": "12826",
    "name": "twitch",
    "display_name": "Twitch",
    "channel_url": "https://www.twitch.tv/twitch",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-8a8c5be2e3b64a9a-300x300.png"
  },
  "curator": {
    "id": "59222117",
    "name": "skiptoplay",
    "display_name": "SkipToPlay",
    "channel_url": "https://www.twitch.tv/skiptoplay",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/skiptoplay-profile_image-1d66e001a46b0c9d-300x300.png"
  },
  "vod": {
    "id": "107049351",
    "url": "https://www.twitch.tv/videos/107049351?t=0s"
  },
  "game": "",
  "language": "en",
  "title": "Clip Title Editing",
  "views": 106,
  "duration": 32.000333,
  "created_at": "2016-12-14T16:28:49Z",
  "thumbnails": {
    "medium": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-480x272.jpg",
    "small": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-260x147.jpg",
    "tiny": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-86x45.jpg"
  }
}

Get Top Clips

✎

Gets the top clips which meet a specified set of parameters.

Authentication

None

URL

GET https://api.twitch.tv/kraken/clips/top

Optional Query String Parameters

Name	Type	Description
`channel`	string	Channel name. If this is specified, top clips for only this channel are returned; otherwise, top clips for all channels are returned. If both `channel` and `game` are specified, `game` is ignored.
`cursor`	string	Tells the server where to start fetching the next set of results, in a multi-page response.
`game`	string	Game name. (Game names can be retrieved with the Search Games endpoint.) If this is specified, top clips for only this game are returned; otherwise, top clips for all games are returned. If both `channel` and `game` are specified, `game` is ignored.
`language`	string	Comma-separated list of languages, which constrains the languages of videos returned. Examples: `es`, `en,es,th`. If no language is specified, all languages are returned. Default: `""`. Maximum: 28 languages.
`limit`	long	Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
`period`	string	The window of time to search for clips. Valid values: `day`, `week`, `month`, `all`. Default: `week`.
`trending`	boolean	If `true`, the clips returned are ordered by popularity; otherwise, by viewcount. Default: `false`.

Example Request

This gets the most popular clip on the Twitch channel during the last month.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/clips/top?channel=Twitch&period=month&trending=true&limit=1'

Example Response

{
  "clips": [
    {
      "slug": "ShakingPoliteQuailGingerPower",
      "tracking_id": "64579613",
      "url": "https://clips.twitch.tv/ShakingPoliteQuailGingerPower?tt_medium=clips_api&tt_content=url",
      "embed_url": "https://clips.twitch.tv/embed?clip=ShakingPoliteQuailGingerPower&tt_medium=clips_api&tt_content=embed",
      "embed_html": "",
      "broadcaster": {
        "id": "12826",
        "name": "twitch",
        "display_name": "Twitch",
        "channel_url": "https://www.twitch.tv/twitch",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-8a8c5be2e3b64a9a-300x300.png"
      },
      "curator": {
        "id": "151724913",
        "name": "comakarzi",
        "display_name": "comakarzi",
        "channel_url": "https://www.twitch.tv/comakarzi",
        "logo": null
      },
      "vod": {
        "id": "92629129",
        "url": "https://www.twitch.tv/videos/92629129?t=3h6m15s"
      },
      "game": "TwitchCon 2016",
      "language": "en",
      "title": "TwitchCon 2016 - Kappa Theater - Day 3/3 - twitch.tv/twitchcon - twitchcon.com/schedule",
      "views": 3,
      "duration": 32.031678,
      "created_at": "2017-04-05T01:42:38Z",
      "thumbnails": {
        "medium": "https://clips-media-assets.twitch.tv/vod-92629129-offset-11174-preview-480x272.jpg",
        "small": "https://clips-media-assets.twitch.tv/vod-92629129-offset-11174-preview-260x147.jpg",
        "tiny": "https://clips-media-assets.twitch.tv/vod-92629129-offset-11174-preview-86x45.jpg"
      }
    }
  ],
  "_cursor": "Mw=="
}

Get Followed Clips

✎

Gets the top clips for the games followed by a specified user, identified by an OAuth token.

Authentication

Required scope: user_read

URL

GET https://api.twitch.tv/kraken/clips/followed

Optional Query String Parameters

Name	Type	Description
`limit`	long	Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
`cursor`	string	Tells the server where to start fetching the next set of results, in a multi-page response.
`trending`	boolean	If `true`, the clips returned are ordered by popularity; otherwise, by viewcount. Default: `false`.

Example Request

This gets the top clip for games followed by the user identified by OAuth token cfabdegwdoklmawdzdo98xt2fo512y. Results are ordered by popularity.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/clips/followed?trending=true&limit=1'

Example Response

{
  "clips": [
    {
      "slug": "DeliciousExcitedSalmonStinkyCheese",
      "tracking_id": "13211072",
      "url": "https://clips.twitch.tv/DeliciousExcitedSalmonStinkyCheese?tt_medium=clips_api&tt_content=url",
      "embed_url": "https://clips.twitch.tv/embed?clip=DeliciousExcitedSalmonStinkyCheese&tt_medium=clips_api&tt_content=embed",
      "embed_html": "",
      "broadcaster": {
        "id": "52968416",
        "name": "asmodaitv",
        "display_name": "AsmodaiTV",
        "channel_url": "https://www.twitch.tv/asmodaitv",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/asmodaitv-profile_image-0f62202546cff589-300x300.png"
      },
      "curator": {
        "id": "32879573",
        "name": "zoterek",
        "display_name": "Zoterek",
        "channel_url": "https://www.twitch.tv/zoterek",
        "logo": null
      },
      "vod": {
        "id": "107324228",
        "url": "https://www.twitch.tv/videos/107324228?t=6h4m29s"
      },
      "game": "Hearthstone",
      "language": "no",
      "title": "CoL.Asmodai Legend Ladder",
      "views": 182047,
      "duration": 29.999667,
      "created_at": "2016-12-14T08:59:02Z",
      "thumbnails": {
        "medium": "https://clips-media-assets.twitch.tv/23926639360-offset-21868-preview-480x272.jpg",
        "small": "https://clips-media-assets.twitch.tv/23926639360-offset-21868-preview-260x147.jpg",
        "tiny": "https://clips-media-assets.twitch.tv/23926639360-offset-21868-preview-86x45.jpg"
      }
    }
  ],
  "_cursor": "MQ=="
}