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 Search API lets you query YouTube Music for songs, videos, albums, artists, and playlists. All methods are suspend functions on the YouTube singleton and return a Result<T> wrapping the parsed response.
Performs a filtered search and returns a single page of typed results. 
suspend fun search(query: String, filter: SearchFilter): Result<SearchResult>
​
query
String
required
The search query string (e.g. "Bohemian Rhapsody").
​
filter
SearchFilter
required
A SearchFilter constant that restricts results to a specific content type. See SearchFilter Constants below.

​
Returns

Result<SearchResult>
​
items
List<YTItem>
Parsed results for the current page. Each element is one of SongItem, VideoItem, AlbumItem, ArtistItem, or PlaylistItem, depending on the filter applied.
​
continuation
String?
An opaque continuation token. Pass this to searchContinuation() to fetch the next page. null when there are no more results.

​
Example

import com.music.innertube.YouTube

// Search for songs matching a query
val result = YouTube.search("Blinding Lights", YouTube.SearchFilter.FILTER_SONG)
    .getOrThrow()

result.items.forEach { item ->
    println(item) // SongItem, AlbumItem, etc.
}

// Paginate
var token = result.continuation
while (token != null) {
    val next = YouTube.searchContinuation(token).getOrThrow()
    next.items.forEach { println(it) }
    token = if (next.items.isEmpty()) null else next.continuation
}

​
YouTube.searchContinuation()

Fetches the next page of a previous search() call using a continuation token. 
suspend fun searchContinuation(continuation: String): Result<SearchResult>
​
continuation
String
required
The opaque continuation token returned by a prior search() or searchContinuation() call.

​
Returns

Result<SearchResult>
​
items
List<YTItem>
The next page of results. Will be empty on the last page.
​
continuation
String?
The next continuation token, or null when items is empty (last page).
When items is empty the library automatically returns continuation = null, so a while (token != null) loop is safe.

​
YouTube.searchSuggestions()

Returns type-ahead search suggestions for a partial query. 
suspend fun searchSuggestions(query: String): Result<SearchSuggestions>
​
query
String
required
Partial or full query string (e.g. "blind" to get completions like "Blinding Lights").

​
Returns

Result<SearchSuggestions>
​
queries
List<String>
Plain-text query completions suggested by YouTube Music.
​
recommendedItems
List<YTItem>
Pre-parsed recommended items (songs, artists, etc.) surfaced alongside textual suggestions.

​
Example

val suggestions = YouTube.searchSuggestions("blind").getOrThrow()

// Text completions
suggestions.queries.forEach { println(it) }
// → "Blinding Lights", "Blind", "Blind Channel", ...

// Recommended items
suggestions.recommendedItems.forEach { println(it) }

​
YouTube.searchSummary()

Performs an unfiltered search and groups results into labelled sections (Top Result, Songs, Videos, Albums, Artists, Playlists). 
suspend fun searchSummary(query: String): Result<SearchSummaryPage>
​
query
String
required
The search query string.

​
Returns

Result<SearchSummaryPage>
​
summaries
List<SearchSummary>
An ordered list of result groups. Each group surfaces a different content category.

​
Example

val summary = YouTube.searchSummary("Queen").getOrThrow()

summary.summaries.forEach { section ->
    println("=== ${section.title} ===")
    section.items.forEach { println("  $it") }
}
// === Top Result ===
//   ArtistItem(id=UCiMhD4jzUqG-IgPzUmmytRQ, title=Queen, ...)
// === Songs ===
//   SongItem(id=..., title=Bohemian Rhapsody, ...)
// ...

​
SearchFilter Constants

SearchFilter is a Kotlin value class wrapping a URL-encoded protobuf param string. All constants live in YouTube.SearchFilter.Companion.
ConstantFilters forEncoded value
FILTER_SONGAudio tracksEgWKAQIIAWoKEAkQBRAKEAMQBA%3D%3D
FILTER_VIDEOMusic videosEgWKAQIQAWoKEAkQChAFEAMQBA%3D%3D
FILTER_ALBUMAlbums & EPsEgWKAQIYAWoKEAkQChAFEAMQBA%3D%3D
FILTER_ARTISTArtist channelsEgWKAQIgAWoKEAkQChAFEAMQBA%3D%3D
FILTER_FEATURED_PLAYLISTYouTube-curated playlistsEgeKAQQoADgBagwQDhAKEAMQBRAJEAQ%3D
FILTER_COMMUNITY_PLAYLISTUser-created playlistsEgeKAQQoAEABagoQAxAEEAoQCRAF
// Usage
YouTube.search("workout", YouTube.SearchFilter.FILTER_COMMUNITY_PLAYLIST)
YouTube.search("adele",   YouTube.SearchFilter.FILTER_ALBUM)
YouTube.search("drake",   YouTube.SearchFilter.FILTER_ARTIST)
Use searchSummary() rather than search() when you want a cross-category overview — it fires a single unfiltered request and groups results automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us