Skip to main content

​
Query Parameters

​
handle
string
A YouTube @handle or custom URL slug to resolve (e.g. @YouTube, youtube). Provide either handle or url.
​
url
string
Any YouTube URL to resolve (channel, video, or playlist). Provide either handle or url.

​
Response

​
input
string
The handle or URL that was resolved.
​
type
string
Resolved entity type: channel, video, or playlist (nullable).
​
channel_id
string
Canonical channel id, if applicable (nullable).
​
channel_username
string
Channel @handle, if applicable (nullable).
​
video_id
string
Video id, if the input resolved to a video (nullable).
​
playlist_id
string
Playlist id, if the input resolved to a playlist (nullable).
​
canonical_url
string
The canonical URL of the resolved entity (nullable).

​
Example Response

{
  "input": "@YouTube",
  "type": "channel",
  "channel_id": "UCBR8-60-B28hp2BmDPdntcQ",
  "channel_username": "@YouTube",
  "video_id": null,
  "playlist_id": null,
  "canonical_url": "https://www.youtube.com/channel/UCBR8-60-B28hp2BmDPdntcQ"
}
A resolve request costs 2 credits. Failed requests are not charged.

​
Reference & Utility Endpoints

These low-cost helper endpoints share this section.

​
oEmbed

GET /v1/youtube/oembed?url=... returns YouTube’s public oEmbed metadata for a video or playlist URL — title, author_name, author_url, thumbnail_url, html embed snippet, and dimensions. Costs 1 credit. 
{
  "type": "video",
  "version": "1.0",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video)",
  "author_name": "Rick Astley",
  "author_url": "https://www.youtube.com/@RickAstleyYT",
  "provider_name": "YouTube",
  "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/dQw4w9WgXcQ\"></iframe>",
  "width": 480,
  "height": 270
}

​
Categories

GET /v1/youtube/categories?gl=US returns the video category reference list for a region. Each row has id and title. Free (0 credits). 
{ "gl": "US", "categories": [ { "id": "10", "title": "Music" }, { "id": "20", "title": "Gaming" } ] }

​
Languages

GET /v1/youtube/languages returns the supported UI languages (valid hl values), each with id (code) and title. Free (0 credits). 
{ "languages": [ { "id": "en", "title": "English" }, { "id": "de", "title": "German" } ] }

​
Regions

GET /v1/youtube/regions returns the supported content regions (valid gl values), each with id (code) and title. Free (0 credits). 
{ "regions": [ { "id": "US", "title": "United States" }, { "id": "GB", "title": "United Kingdom" } ] }

​
Markets

GET /v1/youtube/markets returns the supported markets reference (region + language pairings). Free (0 credits).
oEmbed costs 1 credit; categories, languages, regions, and markets are free reference endpoints (0 credits). Failed requests are not charged.