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.

The search API exposes four coroutine functions on the YouTube singleton. Use search() for filtered, paginated results; searchSuggestions() for autocomplete; searchSummary() for a multi-category overview; and searchContinuation() to page through a previous search() call.
Returns a page of items matching query narrowed to a single content type by filter. 
suspend fun search(query: String, filter: SearchFilter): Result<SearchResult>
​
query
String
required
The search query string entered by the user.
​
filter
SearchFilter
required
Restricts results to a single content category. Pass one of the SearchFilter companion constants — for example SearchFilter.FILTER_SONG.
Return type
​
Result<SearchResult>
Result
A Kotlin Result wrapping a SearchResult on success, or an exception on failure.
Example 
val result = YouTube.search("Daft Punk", YouTube.SearchFilter.FILTER_SONG)
result.onSuccess { page ->
    page.items.filterIsInstance<SongItem>().forEach { song ->
        println("${song.title} — ${song.artists.joinToString { it.name }}")
    }
    page.continuation?.let { token ->
        // fetch next page
        YouTube.searchContinuation(token)
    }
}

​
YouTube.searchSuggestions

Returns autocomplete suggestions and recommended items for a partial query string. 
suspend fun searchSuggestions(query: String): Result<SearchSuggestions>
​
query
String
required
The partial or complete query string to generate suggestions for.
Return type
​
Result<SearchSuggestions>
Result
A Result wrapping a SearchSuggestions object.
Example 
YouTube.searchSuggestions("billie").onSuccess { suggestions ->
    suggestions.queries.forEach { println(it) }
    suggestions.recommendedItems.forEach { item ->
        println("${item.title} (${item::class.simpleName})")
    }
}

​
YouTube.searchSummary

Performs a full search and groups the top results into titled sections — one section per content category. Useful for building a “search overview” screen that shows a sample from every type. 
suspend fun searchSummary(query: String): Result<SearchSummaryPage>
​
query
String
required
The search query string.
Return type
​
Result<SearchSummaryPage>
Result
A Result wrapping a SearchSummaryPage.
Example 
YouTube.searchSummary("The Beatles").onSuccess { page ->
    page.summaries.forEach { section ->
        println("=== ${section.title} ===")
        section.items.take(3).forEach { println("  • ${it.title}") }
    }
}

​
YouTube.searchContinuation

Fetches the next page of results from a previous search() call using the continuation token returned in SearchResult.continuation. 
suspend fun searchContinuation(continuation: String): Result<SearchResult>
​
continuation
String
required
The opaque continuation token obtained from a prior SearchResult.continuation field.
Return type
​
Result<SearchResult>
Result
A Result wrapping a SearchResult. The continuation field of the new result will be null when the last page has been reached.
Example 
var token: String? = null
do {
    val result = if (token == null) {
        YouTube.search("Radiohead", YouTube.SearchFilter.FILTER_SONG)
    } else {
        YouTube.searchContinuation(token)
    }
    result.onSuccess { page ->
        page.items.forEach { println(it.title) }
        token = page.continuation
    }.onFailure { token = null }
} while (token != null)

​
SearchFilter

An inline value class that wraps a URL-encoded parameter string consumed by the InnerTube search endpoint. All constants live in the companion object. 
@JvmInline
value class SearchFilter(val value: String) {
    companion object {
        val FILTER_SONG              = SearchFilter("EgWKAQIIAWoKEAkQBRAKEAMQBA%3D%3D")
        val FILTER_VIDEO             = SearchFilter("EgWKAQIQAWoKEAkQChAFEAMQBA%3D%3D")
        val FILTER_ALBUM             = SearchFilter("EgWKAQIYAWoKEAkQChAFEAMQBA%3D%3D")
        val FILTER_ARTIST            = SearchFilter("EgWKAQIgAWoKEAkQChAFEAMQBA%3D%3D")
        val FILTER_FEATURED_PLAYLIST = SearchFilter("EgeKAQQoADgBagwQDhAKEAMQBRAJEAQ%3D")
        val FILTER_COMMUNITY_PLAYLIST= SearchFilter("EgeKAQQoAEABagoQAxAEEAoQCRAF")
        val FILTER_PODCAST           = SearchFilter("EgWKAQJQAWoKEAkQChAFEAMQBA%3D%3D")
        val FILTER_EPISODE           = SearchFilter("EgWKAQJYAWoKEAkQChAFEAMQBA%3D%3D")
        val FILTER_PROFILE           = SearchFilter("EgWKAQJYAWoSEAUQCRADEAQQEBAVEAoQDhAR")
    }
}
ConstantContent type returned
FILTER_SONGAudio tracks (songs and music videos)
FILTER_VIDEOYouTube Music video clips
FILTER_ALBUMFull albums and EPs
FILTER_ARTISTArtist channel pages
FILTER_FEATURED_PLAYLISTYouTube-curated playlists
FILTER_COMMUNITY_PLAYLISTUser-created public playlists
FILTER_PODCASTPodcast shows
FILTER_EPISODEIndividual podcast episodes
FILTER_PROFILEUser channel profiles

Build docs developers (and LLMs) love

Get started for freeTalk to us