Skip to main content

Documentation Index

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

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

The Library API exposes the authenticated user’s saved songs, albums, playlists, artists, playback history, and account metadata. All methods are suspend functions on the YouTube singleton and return Result<T>.
All library methods require a valid cookie to be set before calling:
YouTube.cookie = "SAPISID=...; ..."
Without a cookie the requests will either fail or return an empty response.

​
YouTube.library()

Fetches a library tab for the authenticated user. 
suspend fun library(browseId: String, tabIndex: Int = 0): Result<LibraryPage>
​
browseId
String
required
The library section to browse. Common values:
Browse IDContent
"FEmusic_library_landing"Main library landing page
"FEmusic_liked_videos"Liked songs
"FEmusic_liked_playlists"Liked / saved playlists
"FEmusic_library_corpus_artists"Subscribed artists
"FEmusic_library_corpus_track_artists"Artists from liked tracks
​
tabIndex
Int
Zero-based index of the tab within the browse page. Defaults to 0 (the first tab). Rarely needed — most library pages have only one tab.

​
Returns

Result<LibraryPage>
​
items
List<YTItem>
The items in this library section. Depending on the browseId, these will be one or more of SongItem, AlbumItem, PlaylistItem, or ArtistItem.
​
continuation
String?
Token for fetching more items via libraryContinuation(). null when all items are on this page.

​
LibraryFilter Constants

LibraryFilter is a Kotlin value class wrapping a URL-encoded continuation param string. The constants live in YouTube.LibraryFilter.Companion and are used internally by libraryRecentActivity() and can be passed as continuation tokens.
ConstantDescriptionEncoded value
FILTER_RECENT_ACTIVITYRecently interacted items (mixed types)4qmFsgIrEhdGRW11c2ljX2xpYnJhcnlfbGFuZGluZxoQZ2dNR0tnUUlCaEFCb0FZQg%3D%3D
FILTER_RECENTLY_PLAYEDRecently played songs4qmFsgIrEhdGRW11c2ljX2xpYnJhcnlfbGFuZGluZxoQZ2dNR0tnUUlCUkFCb0FZQg%3D%3D
FILTER_PLAYLISTS_ALPHABETICALLiked playlists sorted A→Z4qmFsgIrEhdGRW11c2ljX2xpa2VkX3BsYXlsaXN0cxoQZ2dNR0tnUUlBUkFBb0FZQg%3D%3D
FILTER_PLAYLISTS_RECENTLY_SAVEDLiked playlists sorted by date saved4qmFsgIrEhdGRW11c2ljX2xpa2VkX3BsYXlsaXN0cxoQZ2dNR0tnUUlBQkFCb0FZQg%3D%3D

​
YouTube.libraryContinuation()

Fetches the next page of items from a library section. 
suspend fun libraryContinuation(continuation: String): Result<LibraryContinuationPage>
​
continuation
String
required
The continuation token from LibraryPage.continuation or a previous LibraryContinuationPage.continuation.

​
Returns

Result<LibraryContinuationPage>
​
items
List<YTItem>
Next page of library items.
​
continuation
String?
Token for the following page. null when all items have been loaded.

​
YouTube.libraryRecentActivity()

Fetches the user’s recently interacted items (songs, albums, playlists, artists) from the library landing page using the FILTER_RECENT_ACTIVITY continuation token. 
suspend fun libraryRecentActivity(): Result<LibraryPage>

​
Returns

Result<LibraryPage>
​
items
List<YTItem>
Mixed list of recently interacted SongItem, AlbumItem, PlaylistItem, and ArtistItem entries, ordered by recency.For ArtistItem entries, the implementation automatically fetches the full artist page via artist() and injects the playEndpoint — which is absent in the library grid renderer. The thumbnail from the library grid is preserved so the square aspect ratio is maintained.
​
continuation
String?
Always null — this endpoint returns a single page.

​
YouTube.musicHistory()

Fetches the user’s full listening history grouped by time period. 
suspend fun musicHistory(): Result<HistoryPage>

​
Returns

Result<HistoryPage>
​
sections
List<HistorySection>?
History grouped into time-period sections. null if the response is empty (e.g. history is disabled).

​
YouTube.accountInfo()

Fetches the display name, email, channel handle, and avatar thumbnail of the authenticated account. 
suspend fun accountInfo(): Result<AccountInfo>

​
Returns

Result<AccountInfo>
​
name
String
The Google account display name.
​
email
String?
The Google account email address, if available in the account menu response.
​
channelHandle
String?
The YouTube channel handle (e.g. "@username"), if set.
​
thumbnailUrl
String?
URL of the account profile picture thumbnail.

​
YouTube.refreshVisitorData()

Fetches a fresh visitorData token from YouTube and stores it in YouTube.visitorData. Call this on app launch for unauthenticated (guest) sessions to ensure accurate regional and localisation data. 
suspend fun refreshVisitorData(): Result<String>

​
Returns

Result<String> — the new visitor data string (also stored in YouTube.visitorData).

​
Example

// On app start for guest/unauthenticated sessions
YouTube.refreshVisitorData().onFailure {
    println("Could not fetch visitor data: ${it.message}")
}

​
YouTube.clearGuestSession()

Clears the stored visitorData and dataSyncId, effectively resetting the guest session context. 
fun clearGuestSession()
Both YouTube.visitorData and YouTube.dataSyncId are set to null. Use this when logging out or switching accounts.

​
Example: Browse the library

import com.music.innertube.YouTube
import com.music.innertube.models.SongItem
import com.music.innertube.models.PlaylistItem

// Set authentication cookie
YouTube.cookie = "SAPISID=...; ..."

// ── Account info ─────────────────────────────────────────────────────────────
val account = YouTube.accountInfo().getOrThrow()
println("Signed in as: ${account.name} (${account.email})")

// ── Liked songs ──────────────────────────────────────────────────────────────
var likedPage = YouTube.library("FEmusic_liked_videos").getOrThrow()
val allLikedSongs = likedPage.items.filterIsInstance<SongItem>().toMutableList()

var token = likedPage.continuation
while (token != null) {
    val next = YouTube.libraryContinuation(token).getOrThrow()
    allLikedSongs += next.items.filterIsInstance<SongItem>()
    token = next.continuation
}
println("Liked songs: ${allLikedSongs.size}")

// ── Liked playlists ───────────────────────────────────────────────────────────
val playlistsPage = YouTube.library("FEmusic_liked_playlists").getOrThrow()
playlistsPage.items.filterIsInstance<PlaylistItem>().forEach {
    println("  Playlist: ${it.title}")
}

// ── Recent activity ───────────────────────────────────────────────────────────
val recent = YouTube.libraryRecentActivity().getOrThrow()
println("Recently played: ${recent.items.size} items")

// ── Listening history ─────────────────────────────────────────────────────────
val history = YouTube.musicHistory().getOrThrow()
history.sections?.forEach { section ->
    println("=== ${section.title} ===")
    section.songs.take(5).forEach { song ->
        println("  ${song.title} — ${song.artists.joinToString { it.name }}")
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us