YouTube channels.list can look up a channel by its @handle with forHandle

Announced31 Jan 2024

Effective31 Jan 2024

StatusIn effect

What changed

YouTube's January 31, 2024 Data API revision adds a forHandle parameter to channels.list, which retrieves information about a channel by specifying its YouTube handle. channels.list costs 1 quota unit in the shared bucket, while search.list now has its own bucket of 100 calls a day, so forHandle is the cheaper way to find a channel from its handle.

What it means

Tools can turn a channel's @handle straight into channel data with one channels.list call at 1 quota unit, instead of searching for it.

Who is affected

Scheduling, analytics and monitoring tools where users type or paste a YouTube @handle, such as competitor tracking or channel connection screens.

What to do by 31 Jan 2024

Use channels.list with the forHandle parameter to resolve a handle to a channel ID, instead of search.list.

What this means for you

Every YouTube channel has a short name that starts with @, like @mybakery. Before this change, apps had to search YouTube to find which channel a short name belonged to. Now they can ask YouTube directly: "which channel is @mybakery?" It is faster, cheaper and less likely to pick the wrong channel.

The details

Parameter: channels.list gained forHandle, which "enables you to retrieve information about a channel by specifying its YouTube handle."
Value: the handle with or without the @, for example GoogleDevelopers or @GoogleDevelopers.
Filter: only one of id, categoryId, mine, managedByMe, forHandle and forUsername may be set per request, or the API returns invalidCriteria (400). With onBehalfOfContentOwner, only id or managedByMe is allowed.
Quota: channels.list costs 1 unit in the shared bucket. search.list has had its own bucket of 100 calls a day since June 2026 (our entry), so resolving handles through search is now the scarcer option.
Related: forUsername is a separate filter for YouTube usernames.

What to do next

Business owners: Nothing.
Marketers and agencies: Nothing, unless your tool asks you for a channel ID: it should accept an @handle instead.
Developers: Resolve user-entered handles by calling channels.list with forHandle (and part=id,snippet), then store the returned channel ID.

Follow new entries with the RSS feed. Each platform also has its own feed, for example X or Meta.