innertube Python Client

The innertube library interacts with Google's private InnerTube API, which differs from the official YouTube Data API in several ways:

• Google Account: Not required for innertube, whereas it is required for the Data API.
• Request Limits: innertube has very high limits (effectively no practical limit), while the Data API has a strict daily quota (default 10,000 units).
• Data Quality: The Data API provides clean, structured data. innertube returns raw data from the internal API, which requires manual parsing and sanitization to extract useful information.

Use innertube when you need access to data not exposed by the official Data API.

You can install the latest stable release of innertube from PyPI using pip.

pip install innertube

To install the latest development version directly from the GitHub repository, use the following command:

pip install git+https://github.com/tombulled/innertube@develop

To handle regionalized API requests, innertube uses a hierarchy of locale abstractions:

1. Language: Defines the specific language and its native name using IETF BCP-47 tags (e.g., Language.JAPANESE).
2. Location: Defines the geographic region using ISO 3166-1 alpha-2 codes (e.g., Location.JAPAN).
3. Locale: Composes a Language and a Location into a single object.

When you create a Locale, you can pass in the high-level enum objects or simple strings. The Locale object then provides the accept_language() method, which formats these components into a single string suitable for request headers or API parameters.

These dataclasses are used to model the metadata and structure of API responses.

ResponseContext

Contains nested dataclasses that describe the state of the request/response:

• Request: Contains type and id.
• Client: Contains name and version.
• Flags: Contains logged_in (bool).
• Other fields include function, browse_id, context, and visitor_data.

ResponseFingerprint

Used to track or identify specific request patterns. It contains optional strings for:

• request
• function
• browse_id
• context
• client

To use the library, import innertube and instantiate an InnerTube client by specifying the service type (e.g., `

import innertube

# Construct a client for the WEB service
client = innertube.InnerTube("WEB")

# Use high-level methods like search()
data = client.search(query="foo fighters")

# Use high-level methods like browse()
# Note: browse() takes the browseId as a positional argument
data = client.browse("FEwhat_to_watch")

# Alternatively, dispatch requests manually using the client as a callable
# This allows you to call any endpoint by passing the endpoint name and a body dictionary
data = client("browse", body={"browseId": "FEwhat_to_watch"})

The following core endpoints are currently implemented as unauthenticated methods. Availability varies by service (YouTube, YouTubeMusic, YouTubeKids, YouTubeStudio):

Call next() to get the next set of items in a sequence. It accepts either a video_id or a playlist_id, along with an optional index (as playlistIndex) and continuation token.

next_items = client.next(video_id="videoId", index=5)

The package exports InnerTube and Client for managing API sessions, and config for managing global or instance-specific settings. InnerTube is typically used as the high-level interface for end-users.

from innertube import InnerTube, config

# Access or modify configuration
print(config)

client = InnerTube()

Call browse(browse_id=...) to fetch content associated with a specific browseId. Supports params and continuation for pagination.

feed_data = client.browse(browse_id="FBEb")

The get_response_context(data) function parses the responseContext field from a raw InnerTube response dictionary. It extracts service tracking parameters (like CSI and GFEEDBACK) to build a ResponseContext object containing:

• function: The InnerTube function name.
• browse_id: The current browse ID.
• context: The context data.
• visitor_data: The visitor data.
• request: An object containing the type and id (extracted from Get..._rid keys in the CSI service).
• client: An object containing the client name and version.
• flags: A Flags object indicating if the user is logged_in.

from innertube.api import get_response_context

response_context = get_response_context(data)
if response_context:
    print(f"Request Type: {response_context.request.type}")
    print(f"Logged In: {response_context.flags.logged_in}")