Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/faraasaaay/inner/llms.txt

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

The YouTube object exposes four search-related suspend functions covering typed search, pagination, cross-category summaries, and autocomplete suggestions. All functions return Result<T> — use getOrThrow(), getOrNull(), or onSuccess/onFailure to handle outcomes.

​
search(query, filter)

Performs a filtered search against YouTube Music and returns the first page of results. 
val result = YouTube.search("Daft Punk", YouTube.SearchFilter.FILTER_SONG)
result.onSuccess { page ->
    page.items.forEach { println(it) }
    println("Continuation token: ${page.continuation}")
}
​
query
String
required
The search query string.
​
filter
YouTube.SearchFilter
required
Restricts results to a single content type. See SearchFilter values below.
​
items
List<YTItem>
Parsed result items. The concrete type depends on the filter used: SongItem, VideoItem, AlbumItem, ArtistItem, or PlaylistItem.
​
continuation
String?
Opaque token. Pass to searchContinuation() to retrieve the next page. null when no further pages are available.

​
searchContinuation(continuation)

Fetches the next page of results for a previous search() call. 
val firstPage = YouTube.search("Radiohead", YouTube.SearchFilter.FILTER_ALBUM).getOrThrow()
val token = firstPage.continuation ?: return

val nextPage = YouTube.searchContinuation(token).getOrThrow()
nextPage.items.forEach { println(it) }
​
continuation
String
required
The continuation token returned by a previous search() or searchContinuation() call.
​
items
List<YTItem>
The next page of result items. Empty list if there are no more results.
​
continuation
String?
Token for the page after this one, or null when results are exhausted.

​
searchSummary(query)

Returns a multi-category summary of search results, similar to YouTube Music’s default search page. Results are grouped into named sections such as “Top result”, “Songs”, “Albums”, “Artists”, and “Playlists”. 
val summary = YouTube.searchSummary("The Beatles").getOrThrow()
summary.summaries.forEach { section ->
    println("Section: ${section.title} — ${section.items.size} items")
    section.items.forEach { println("  $it") }
}
​
query
String
required
The search query string.
​
summaries
List<SearchSummary>
Ordered list of result groups.

​
searchSuggestions(query)

Returns autocomplete suggestions and recommended items for a partial query string, as shown in the YouTube Music search bar. 
val suggestions = YouTube.searchSuggestions("tay").getOrThrow()
println("Query suggestions: ${suggestions.queries}")
suggestions.recommendedItems.forEach { println("Recommended: $it") }
​
query
String
required
A partial or complete query string to get suggestions for.
​
queries
List<String>
Autocomplete text suggestions derived from the query.
​
recommendedItems
List<YTItem>
Pre-resolved content items (songs, artists, etc.) recommended alongside the text suggestions.

​
SearchFilter values

YouTube.SearchFilter is a @JvmInline value class wrapping the encoded InnerTube filter string. Always reference constants via YouTube.SearchFilter.FILTER_*.
ConstantEncoded valueMatches
FILTER_SONGEgWKAQIIAWoKEAkQBRAKEAMQBA%3D%3DAudio tracks
FILTER_VIDEOEgWKAQIQAWoKEAkQChAFEAMQBA%3D%3DMusic videos
FILTER_ALBUMEgWKAQIYAWoKEAkQChAFEAMQBA%3D%3DAlbums and EPs
FILTER_ARTISTEgWKAQIgAWoKEAkQChAFEAMQBA%3D%3DArtist channels
FILTER_FEATURED_PLAYLISTEgeKAQQoADgBagwQDhAKEAMQBRAJEAQ%3DOfficial / featured playlists
FILTER_COMMUNITY_PLAYLISTEgeKAQQoAEABagoQAxAEEAoQCRAFUser-created playlists
SearchFilter is a value class — it carries zero runtime overhead compared to a plain String. Use the named constants rather than constructing a SearchFilter directly to avoid encoding mistakes.

​
Usage example

// Search for albums
val albums = YouTube.search("Pink Floyd", YouTube.SearchFilter.FILTER_ALBUM)
    .getOrThrow()
    .items
    .filterIsInstance<com.tamed.music.innertube.models.AlbumItem>()

// Search for community playlists with pagination
var continuation: String? = null
do {
    val page = if (continuation == null) {
        YouTube.search("lo-fi", YouTube.SearchFilter.FILTER_COMMUNITY_PLAYLIST).getOrThrow()
    } else {
        YouTube.searchContinuation(continuation).getOrThrow()
    }
    page.items.forEach { println(it) }
    continuation = page.continuation
} while (continuation != null)

Build docs developers (and LLMs) love

Get started for freeTalk to us