Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/faraasaaay/innertube-v1/llms.txt

Use this file to discover all available pages before exploring further.

InnerTube API responses are parsed into strongly typed page data classes rather than raw JSON. Each page class corresponds to a specific browse, search, or player endpoint. Fields use the YTItem hierarchy for content items, BrowseEndpoint for navigation links, and WatchEndpoint for playback. Continuation tokens are plain String? values that can be passed back to the corresponding API method to fetch the next page of results.

​
SearchResult

Returned by the primary search endpoint for a single content-type filter (e.g., songs only, albums only). 
data class SearchResult(
    val items: List<YTItem>,
    val continuation: String? = null,
)
​
items
List<YTItem>
required
Ordered list of search results. Each element is one of SongItem, AlbumItem, ArtistItem, PlaylistItem, PodcastItem, or EpisodeItem depending on the active filter.
​
continuation
String?
Opaque continuation token for fetching the next page of results. null when no further pages are available.

​
SearchSuggestions

Returned by the search-suggestions endpoint as the user types a query. 
data class SearchSuggestions(
    val queries: List<String>,
    val recommendedItems: List<YTItem>,
)
​
queries
List<String>
required
Ordered list of query completion strings suggested by YouTube Music.
​
recommendedItems
List<YTItem>
required
Content items recommended alongside the text suggestions (typically recent songs or top results for the partial query).

​
SearchSummaryPage and SearchSummary

Returned by a top-level search with no content-type filter. The results are grouped into multiple sections (one per content type present), each wrapped in a SearchSummary. 
data class SearchSummaryPage(
    val summaries: List<SearchSummary>,
)

data class SearchSummary(
    val title: String,
    val items: List<YTItem>,
)

​
SearchSummaryPage

​
summaries
List<SearchSummary>
required
Ordered list of per-type result groups. Typical titles include "Songs", "Albums", "Artists", "Playlists", and "Podcasts".
SearchSummaryPage also exposes filterExplicit(enabled: Boolean), filterVideoSongs(disableVideos: Boolean), and filterYoutubeShorts(enabled: Boolean) convenience methods that apply the corresponding YTItem list filters to every summary section, dropping any section that becomes empty.

​
SearchSummary

​
title
String
required
Localised section heading (e.g., "Songs", "Artists").
​
items
List<YTItem>
required
The top results for this content type. InnerTube typically returns a small preview (3–5 items) in summary mode.

​
ArtistPage

Returned when browsing an artist channel. Contains the artist’s metadata, all carousel/shelf sections, and subscription state. 
data class ArtistPage(
    val artist: ArtistItem,
    val sections: List<ArtistSection>,
    val description: String?,
    val subscriberCountText: String?,
    val monthlyListenerCount: String? = null,
    val descriptionRuns: List<Run>? = null,
    val isSubscribed: Boolean = false,
)
​
artist
ArtistItem
required
The artist’s core metadata (id, title, thumbnail, endpoints).
​
sections
List<ArtistSection>
required
Ordered list of content sections on the artist page (e.g., "Popular", "Albums", "Singles", "Videos", "Featured on", "Fans also like"). Each section contains its own item list.
​
description
String?
Plain-text artist biography, if provided by the API.
​
subscriberCountText
String?
Localised subscriber count string (e.g., "4.2M subscribers").
​
monthlyListenerCount
String?
Localised monthly listener count string when available on the page header.
​
descriptionRuns
List<Run>?
Structured rich-text runs for the biography, preserving navigation endpoints (e.g., links to other artists mentioned in the bio).
​
isSubscribed
Boolean
true when the authenticated user is already subscribed to this artist channel.

​
ArtistSection

A single content carousel or shelf on an ArtistPage. 
data class ArtistSection(
    val title: String,
    val items: List<YTItem>,
    val moreEndpoint: BrowseEndpoint?,
)
​
title
String
required
Section heading as returned by the API.
​
items
List<YTItem>
required
Items displayed in the section. Type varies by section: SongItem for Popular, AlbumItem for Albums/Singles, PlaylistItem for playlists, ArtistItem for Fans Also Like.
​
moreEndpoint
BrowseEndpoint?
Browse endpoint for the “Show all” / “More” button. null when the section shows the complete list already.

​
AlbumPage

Returned when browsing an album or EP. Contains full track listing and alternate release versions. 
data class AlbumPage(
    val album: AlbumItem,
    val songs: List<SongItem>,
    val otherVersions: List<AlbumItem>,
)
​
album
AlbumItem
required
Album metadata: title, artists, year, artwork, and both browse and playlist IDs.
​
songs
List<SongItem>
required
Ordered list of tracks. Each SongItem has its album field pre-populated with the parent album’s name and browse ID.
​
otherVersions
List<AlbumItem>
required
Alternate releases of the same album (e.g., a deluxe edition, a remaster, or a regional variant). Empty list when none are available.

​
PlaylistPage

Returned when browsing a user playlist. Songs and the playlist continuation are paged separately. 
data class PlaylistPage(
    val playlist: PlaylistItem,
    val songs: List<SongItem>,
    val songsContinuation: String?,
    val continuation: String?,
)
​
playlist
PlaylistItem
required
Playlist metadata including title, author, thumbnail, and play/shuffle/radio endpoints.
​
songs
List<SongItem>
required
First page of tracks in the playlist. Each SongItem has setVideoId populated for playlist management operations.
​
songsContinuation
String?
Continuation token for fetching additional tracks within the same playlist shelf.
​
continuation
String?
Continuation token for the outer browse response. Pass to the continuation endpoint to load more playlist content.

​
PlaylistContinuationPage

The continuation result for a PlaylistPage. Returned when passing a continuation token to the playlist browse endpoint. 
data class PlaylistContinuationPage(
    val songs: List<SongItem>,
    val continuation: String?,
)
​
songs
List<SongItem>
required
Next batch of tracks from the playlist. Each item has setVideoId populated.
​
continuation
String?
Token for the next page. null when the end of the playlist has been reached.

​
NextResult

Returned by the next player endpoint and represents the “Up Next” queue alongside the current track context. Used to drive continuous playback and to surface lyrics and related-content endpoints. 
data class NextResult(
    val title: String? = null,
    val items: List<SongItem>,
    val currentIndex: Int? = null,
    val lyricsEndpoint: BrowseEndpoint? = null,
    val relatedEndpoint: BrowseEndpoint? = null,
    val continuation: String?,
    val endpoint: WatchEndpoint,
)
​
title
String?
Playlist or radio title for the current queue (e.g., "Liked Songs"). null for ad-hoc radio queues.
​
items
List<SongItem>
required
Ordered list of songs in the Up Next queue.
​
currentIndex
Int?
Zero-based index of the currently playing track within items. null for continuation pages.
​
lyricsEndpoint
BrowseEndpoint?
Browse endpoint for loading the current track’s lyrics tab.
​
relatedEndpoint
BrowseEndpoint?
Browse endpoint for loading the related tracks / radio seed tab.
​
continuation
String?
Token for loading more Up Next items. null when no more items are available in this queue.
​
endpoint
WatchEndpoint
required
The current (or most-recently-used continuation) watch endpoint. Used to resume the next call for subsequent pages.

​
HomePage

Returned when browsing the YouTube Music home feed. The feed is divided into carousel sections, optionally filtered by mood/genre chips. 
data class HomePage(
    val chips: List<Chip>?,
    val sections: List<Section>,
    val continuation: String? = null,
)
​
chips
List<Chip>?
Optional filter chips displayed at the top of the home feed (e.g., "Relax", "Workout", "New releases"). Each chip carries a BrowseEndpoint to re-fetch the feed filtered by that mood, and a deselectEndPoint to return to the unfiltered view.
​
sections
List<Section>
required
Ordered list of content carousels. Sections can contain any mix of SongItem, AlbumItem, ArtistItem, PlaylistItem, PodcastItem, and EpisodeItem.
​
continuation
String?
Token for loading additional home-feed sections.
HomePage also exposes filterExplicit(enabled: Boolean) and filterVideoSongs(disableVideos: Boolean) methods that apply the filters across every section in place, returning a new HomePage copy.

​
HomePage.Section

data class Section(
    val title: String,
    val label: String?,
    val thumbnail: String?,
    val endpoint: BrowseEndpoint?,
    val items: List<YTItem>,
)
​
title
String
required
Section heading (e.g., "Quick picks", "Recently played", "New releases").
​
label
String?
Optional secondary label (strapline) from the carousel header.
​
thumbnail
String?
Optional header thumbnail URL for sections that include an image in their header.
​
endpoint
BrowseEndpoint?
“More” browse endpoint linked from the section header button. null when the section has no “Show all” link.
​
items
List<YTItem>
required
Items in this carousel. All six YTItem subtypes can appear depending on the section type.

​
HomePage.Chip

data class Chip(
    val title: String,
    val endpoint: BrowseEndpoint?,
    val deselectEndPoint: BrowseEndpoint?,
)
​
title
String
required
Chip label text.
​
endpoint
BrowseEndpoint?
Endpoint to re-fetch the home feed with this chip selected.
​
deselectEndPoint
BrowseEndpoint?
Endpoint to deselect this chip and return to the unfiltered home feed.

​
ExplorePage

Returned by the Explore browse endpoint. Combines new-release album previews with the mood-and-genre navigation grid. 
data class ExplorePage(
    val newReleaseAlbums: List<AlbumItem>,
    val moodAndGenres: List<MoodAndGenres.Item>,
)
​
newReleaseAlbums
List<AlbumItem>
required
Curated list of recently released albums and EPs surfaced on the Explore page.
​
moodAndGenres
List<MoodAndGenres.Item>
required
Navigable mood and genre tiles. Each MoodAndGenres.Item carries a title, a stripeColor (ARGB long), and a BrowseEndpoint for the genre’s playlist grid.

​
MoodAndGenres

Represents a group of mood/genre navigation tiles inside the Explore page. 
data class MoodAndGenres(
    val title: String,
    val items: List<Item>,
)
​
title
String
required
Section heading for this group of moods/genres (e.g., "Moods & moments", "Genres").
​
items
List<MoodAndGenres.Item>
required
Individual navigable tiles within this group.

​
MoodAndGenres.Item

data class Item(
    val title: String,
    val stripeColor: Long,
    val endpoint: BrowseEndpoint,
)
​
title
String
required
Display label on the tile (e.g., "Chill", "Hip-Hop").
​
stripeColor
Long
required
ARGB colour value for the tile’s left accent stripe, sourced from MusicNavigationButtonRenderer.solid.leftStripeColor.
​
endpoint
BrowseEndpoint
required
Browse endpoint that loads the playlist grid for this mood or genre.

​
ChartsPage

Returned by the Charts browse endpoint. Organises chart data into named sections with a type discriminator. 
data class ChartsPage(
    val sections: List<ChartSection>,
    val continuation: String?,
)
​
sections
List<ChartSection>
required
Ordered list of chart sections (e.g., Top Songs, Trending, New Releases).
​
continuation
String?
Continuation token for fetching additional chart sections.

​
ChartsPage.ChartSection

data class ChartSection(
    val title: String,
    val items: List<YTItem>,
    val chartType: ChartType,
)
​
title
String
required
Section title (e.g., "Top songs", "Trending").
​
items
List<YTItem>
required
Chart entries. Items are SongItem instances with chartPosition and chartChange populated.
​
chartType
ChartType
required
One of TRENDING, TOP, GENRE, or NEW_RELEASES.

​
LibraryPage

Returned when browsing the user’s library. Contains a heterogeneous list of saved content (songs, albums, artists, playlists, podcasts). 
data class LibraryPage(
    val items: List<YTItem>,
    val continuation: String?,
)
​
items
List<YTItem>
required
First page of library items. Can include SongItem (liked songs and uploaded tracks), AlbumItem, ArtistItem, PlaylistItem, and PodcastItem.
​
continuation
String?
Token for fetching the next page of library items. null when all items have been returned.

​
LibraryContinuationPage

Continuation result for a LibraryPage. 
data class LibraryContinuationPage(
    val items: List<YTItem>,
    val continuation: String?,
)
​
items
List<YTItem>
required
Next batch of library items.
​
continuation
String?
Token for the next continuation page. null when the library list is exhausted.

​
LibraryAlbumsPage

A specialised library page that returns only album items, used when browsing the Albums tab in the library. 
data class LibraryAlbumsPage(
    val albums: List<AlbumItem>,
    val continuation: String?,
)
​
albums
List<AlbumItem>
required
Saved albums from the user’s library. Each item includes browseId, playlistId, title, optional artists, optional year, thumbnail, and explicit.
​
continuation
String?
Token for fetching more albums. null when the full library album list has been returned.

​
HistoryPage

Returned when browsing the user’s playback history. History is grouped by time period (e.g., “Today”, “Yesterday”, “Last week”). 
data class HistoryPage(
    val sections: List<HistorySection>?,
)
​
sections
List<HistorySection>?
Time-grouped sections of play history. null when the history feed is empty or the response lacks a shelf.

​
HistoryPage.HistorySection

data class HistorySection(
    val title: String,
    val songs: List<SongItem>,
)
​
title
String
required
Section time-period label (e.g., "Today", "Yesterday").
​
songs
List<SongItem>
required
Songs played in this time period. Each SongItem has historyRemoveToken populated with the feedback token needed to remove the entry from history.

​
MediaInfo

Metadata about a video returned by the video-info endpoint. Contains channel and engagement statistics separate from playback stream data. 
data class MediaInfo(
    val videoId: String,
    val title: String? = null,
    val author: String? = null,
    val authorId: String? = null,
    val authorThumbnail: String? = null,
    val description: String? = null,
    val uploadDate: String? = null,
    val subscribers: String? = null,
    val viewCount: Int? = null,
    val like: Int? = null,
    val dislike: Int? = null,
)
​
videoId
String
required
YouTube video ID this metadata belongs to.
​
title
String?
Video title. null when the endpoint does not include title metadata.
​
author
String?
Channel display name of the uploader.
​
authorId
String?
Channel ID of the uploader.
​
authorThumbnail
String?
URL of the uploader’s channel avatar.
​
description
String?
Full video description text.
​
uploadDate
String?
Upload date string as returned by the API (format varies by locale).
​
subscribers
String?
Localised subscriber count string for the uploading channel.
​
viewCount
Int?
Total view count.
​
like
Int?
Like count. May be null when the channel has hidden like counts.
​
dislike
Int?
Dislike count. Sourced from the Return YouTube Dislike API if integrated; null otherwise.

Build docs developers (and LLMs) love

Get started for freeTalk to us