Skip to main content
GET
Get video files list
This endpoint returns the direct media URLs for a video’s available video formats, along with their resolution, frame rate, bitrate, container and file size.

​
Choosing a region

Media URLs are always resolved from a specific country. By default that is the country your request originates from, falling back to DE when it cannot be determined. Pass regionCode to resolve the request as if it came from somewhere else — use it when a video is region-restricted and returns no formats from the default region. regionCode accepts an ISO 3166-1 alpha-2 code; see Countries for the full list of accepted values.
cURL

​
Downloading the files

The url of each format is a signed, time-limited link served directly by YouTube’s CDN. Two things follow from that:
  • The links expire within a few hours. Request the list right before you download rather than storing the URLs.
  • The links are issued to the host that fetched them, which is Poix — not your own IP address. For most videos this makes no difference and the link downloads from anywhere. For some region-licensed content YouTube additionally restricts playback to the network the link was issued for, and downloading it yourself returns 403 Forbidden.
regionCode does not fix a 403 on download. It controls which region the link is issued for, not which IP address may use it — the link is never issued for your own IP. If you hit one, request a fresh list and retry; the same link frequently succeeds from a different network.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
videoId
string
required

The YouTube video ID

Required string length: 11
Example:

"dQw4w9WgXcQ"

Query Parameters

​
regionCode
enum<string>

Instructs the API to return results as if the request was made from a specific country. ISO 3166 alpha-2 country code.

Available options:
AD,
AE,
AF,
AG,
AI,
AL,
AM,
AN,
AO,
AQ,
AR,
AS,
AT,
AU,
AW,
AX,
AZ,
BA,
BB,
BD,
BE,
BF,
BG,
BH,
BI,
BJ,
BM,
BN,
BO,
BR,
BS,
BT,
BV,
BW,
BY,
BZ,
CA,
CC,
CD,
CF,
CG,
CH,
CI,
CK,
CL,
CM,
CN,
CO,
CR,
CU,
CV,
CX,
CY,
CZ,
DE,
DJ,
DK,
DM,
DO,
DZ,
EC,
EE,
EG,
EH,
ER,
ES,
ET,
EU,
FI,
FJ,
FK,
FM,
FO,
FR,
GA,
GB,
GD,
GE,
GF,
GG,
GH,
GI,
GL,
GM,
GN,
GP,
GQ,
GR,
GS,
GT,
GU,
GW,
GY,
HK,
HM,
HN,
HR,
HT,
HU,
ID,
IE,
IL,
IM,
IN,
IO,
IQ,
IR,
IS,
IT,
JE,
JM,
JO,
JP,
KE,
KG,
KH,
KI,
KM,
KN,
KP,
KR,
KW,
KY,
KZ,
LA,
LB,
LC,
LI,
LK,
LR,
LS,
LT,
LU,
LV,
LY,
MA,
MC,
MD,
ME,
MG,
MH,
MK,
ML,
MM,
MN,
MO,
MP,
MQ,
MR,
MS,
MT,
MU,
MV,
MW,
MX,
MY,
MZ,
NA,
NC,
NE,
NF,
NG,
NI,
NL,
NO,
NP,
NR,
NU,
NZ,
OM,
PA,
PE,
PF,
PG,
PH,
PK,
PL,
PM,
PN,
PR,
PS,
PT,
PW,
PY,
QA,
RE,
RO,
RS,
RU,
RW,
SA,
SB,
SC,
SD,
SE,
SG,
SH,
SI,
SJ,
SK,
SL,
SM,
SN,
SO,
SR,
ST,
SV,
SY,
SZ,
TC,
TD,
TF,
TG,
TH,
TJ,
TK,
TL,
TM,
TN,
TO,
TR,
TT,
TV,
TW,
TZ,
UA,
UG,
UM,
US,
UY,
UZ,
VA,
VC,
VE,
VG,
VI,
VN,
VU,
WF,
WS,
XK,
YE,
YT,
ZA,
ZM,
ZW

Response

Successful response

​
itag
integer
required

The itag of the video format

​
url
string<uri>
required

The URL of the video file

​
mimeType
string
required

The MIME type of the video file

​
bitrate
integer
required

The bitrate of the video in bits per second

​
width
integer
required

The width of the video in pixels

​
height
integer
required

The height of the video in pixels

​
initRange
object
required

The initialization range for the video file

​
indexRange
object
required

The index range for the video file

​
lastModified
string
required

The last modified timestamp of the video file

​
contentLength
string
required

The content length of the video file in bytes

​
quality
string
required

The quality label of the video

​
fps
integer
required

The frames per second of the video

​
qualityLabel
string
required

The quality label of the video (e.g., 720p, 1080p)

​
projectionType
string
required

The projection type of the video

​
averageBitrate
integer
required

The average bitrate of the video in bits per second

​
approxDurationMs
string
required

The approximate duration of the video in milliseconds

​
parsedContentLength
string
required

The parsed content length in a human-readable format

​
lengthSeconds
string
required

The length of the video in seconds

​
parsedLastModified
string
required

The parsed last modified date in ISO 8601 format

​
highReplication
boolean

Indicates if the video has high replication