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.

InnerTube exposes network configuration options directly on the YouTube object. Changes take effect immediately — any option that requires rebuilding the HTTP client (proxy, IP version) does so automatically.

​
HTTP Proxy

Set YouTube.proxy to route all API requests through an HTTP proxy server. The value is a standard java.net.Proxy: 
import java.net.InetSocketAddress
import java.net.Proxy

YouTube.proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("proxy.example.com", 8080))
When you assign a new proxy, the underlying Ktor/OkHttp client is closed and rebuilt automatically so that in-flight requests are not disrupted. Proxy support is applied globally — every InnerTube API call, as well as the OkHttp client inside PoTokenWebView, goes through the configured proxy.
To clear the proxy and return to a direct connection, set YouTube.proxy = null. The client is rebuilt immediately.

​
Proxy Authentication

If your proxy server requires credentials, set YouTube.proxyAuth with a Proxy-Authorization header value. The library sends this header automatically via an okhttp3.Authenticator on every request that receives an HTTP 407 challenge: 
import android.util.Base64

val credentials = "username:password"
YouTube.proxyAuth = "Basic " + Base64.encodeToString(
    credentials.toByteArray(),
    Base64.NO_WRAP
)
proxyAuth is applied at the OkHttp Authenticator level, not as a static request header. This means credentials are only sent after the proxy issues a 407 challenge, which is the correct behaviour for HTTP proxy authentication.

​
IP Version Filtering

YouTube.ipVersion controls which IP address family is used when resolving hostnames. The library installs a custom okhttp3.Dns implementation that filters the system’s resolved addresses:
ValueBehaviour
IpVersion.AUTOUse all addresses returned by the system DNS (default).
IpVersion.IPV4Prefer IPv4 addresses. Falls back to all addresses if no IPv4 is available.
IpVersion.IPV6Prefer IPv6 addresses. Falls back to all addresses if no IPv6 is available.
import com.music.innertube.models.IpVersion

// Force all connections to use IPv4
YouTube.ipVersion = IpVersion.IPV4

// Allow the OS to decide (default)
YouTube.ipVersion = IpVersion.AUTO
Assigning ipVersion rebuilds the HTTP client in the same way as assigning proxy. The same DNS filtering is applied in YTPlayerUtils’s OkHttp instance (used for stream URL validation), so both API calls and CDN probes honour the configured IP version.

​
Connection Pool and Timeouts

The following settings are configured at client construction time and apply to all InnerTube API requests:
SettingValue
Max idle connections10
Connection keep-alive5 minutes
Connect timeout20 seconds
Read timeout20 seconds
Write timeout20 seconds
Ktor request timeout60 seconds
Ktor connect timeout30 seconds
Retry on connection failureEnabled
HTTP/2Enabled (preferred alongside HTTP/1.1)
These are fixed at the library level and cannot be changed at runtime. If you need custom timeouts for a specific use case, create a separate OkHttp client for those requests rather than modifying InnerTube’s shared client.

​
Retry Logic

Every InnerTube endpoint is wrapped with an exponential-backoff retry loop:
  • Max attempts: 3
  • Initial delay: 500 ms
  • Backoff factor: 2.0×
  • Retry condition: java.io.IOException (network errors, socket aborts, timeouts)
The retry schedule for a request that fails twice before succeeding is: 
Attempt 1 → fail → wait 500 ms
Attempt 2 → fail → wait 1000 ms
Attempt 3 → succeed
Cancelled coroutines are respected — if the calling coroutine is cancelled while waiting between retries, delay() throws CancellationException and the loop stops immediately. Errors other than IOException (such as HTTP 4xx responses parsed as exceptions) are not retried.

​
Complete Setup Example

import com.music.innertube.YouTube
import com.music.innertube.models.IpVersion
import android.util.Base64
import java.net.InetSocketAddress
import java.net.Proxy

// Configure an authenticated HTTP proxy
YouTube.proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("proxy.example.com", 8080))
YouTube.proxyAuth = "Basic " + Base64.encodeToString(
    "username:password".toByteArray(),
    Base64.NO_WRAP
)

// Restrict connections to IPv4 only
YouTube.ipVersion = IpVersion.IPV4

// All subsequent API calls use the proxy and IPv4
YouTube.search("Taylor Swift", YouTube.SearchFilter.FILTER_SONG).onSuccess { result ->
    result.items.forEach { println(it.title) }
}
Proxy and IP version settings are effective immediately. You can change them at runtime — for example, switching between a VPN proxy and a direct connection — and the next API call will use the updated configuration automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us