Get a video or Short

Try in Playground

Retrieve a YouTube video with title, description, engagement, publication date, uploader, chapters, recommendations, genre, duration, caption tracks, format metadata, replay graph and paid-promotion information.

GET/v1/youtube/videox-api-key

Headers

Get your API key

x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters

urlstringrequiredquery

YouTube video or Short URL (youtube.com/watch?v=…, youtu.be/…, /shorts/…, /embed/…, /live/…; www, m and music subdomains) or a bare 11-character video ID.

max 2048 chars

Examplehttps://www.youtube.com/watch?v=Vid0000001a

languagestringquery

Optional language code (en, es, pt-BR) sent as the page's Accept-Language; YouTube may still localise differently.

Response fields

116

requestIdstring

Operation identifier for correlation.

Upstream HTTP attempts, decoded bytes and duration.

accounting.upstreamRequestsinteger

Always included.

≥ 0

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

successboolean

True when usable data was returned; inspect status and coverage.

statusenum

success, partial (coverage.warnings names the omission), failed or challenged.

one of: success, partial

typestring

Always video, for Shorts too.

idstring

Video ID from the player response, checked against the request.

titlestring

Video title.

descriptionstringnullable

The description as YouTube renders it (long links shortened with an ellipsis), with line breaks; the raw player description when the rendered text is absent; null when empty.

descriptionLinksstring[]

Every link in the description in text order: external links unwrapped from YouTube's redirect, hashtag pages, channel links and timestamp links as youtube.com URLs.

up to 200 items

commentCountTextstringnullable

Displayed comment count from the comments panel ("2.4M"); null when comments are off.

commentCountIntintegernullable

Comment count parsed from commentCountText.

likeCountTextstringnullable

Exact like count as YouTube publishes it in the page metadata; null when hidden.

likeCountIntintegernullable

Like count as an integer.

viewCountTextstringnullable

Exact view count with thousands separators.

viewCountIntintegernullable

Exact view count.

publishDateTextstringnullable

Displayed date text ("Oct 24, 2009", "Premiered …", "Streamed live on …").

Collaborating channels when YouTube lists them on the watch page.

up to 20 items

collaborators.idstringnullable

Always included.

collaborators.urlstringnullable

Always included.

collaborators.handlestringnullable

Always included.

collaborators.titlestringnullable

Always included.

collaborators.thumbnailstringnullable

Always included.

Uploader: id, url (canonical channel URL), handle ("Name", or "channel/UC…" for channels without a handle), title and 48 px thumbnail.

channel.idstringnullable

Always included.

channel.urlstringnullable

Always included.

channel.handlestringnullable

Always included.

channel.titlestringnullable

Always included.

channel.thumbnailstringnullable

Always included.

Description chapters (auto chapters when none are written): title, timeDescription ("3:54") and startSeconds. Empty when the video has none.

up to 500 items

chapters.titlestring

Always included.

chapters.timeDescriptionstringnullable

Always included.

chapters.startSecondsintegernullable

Always included.

Recommended videos shown next to the video (up to 100): id, title, thumbnail, channel {title, url, handle, id}, publishedTimeText, publishedTime, publishDateText, publishDate, viewCountText (present when a count is shown), viewCountInt, lengthText and lengthInSeconds (present when a duration is shown) and videoUrl. Recommendations differ between requests.

up to 100 items

watchNextVideos.idstring

Always included.

watchNextVideos.titlestring

Always included.

watchNextVideos.thumbnailstringnullable

Always included.

watchNextVideos.channel.titlestringnullable

Always included.

watchNextVideos.channel.urlstringnullable

Always included.

watchNextVideos.channel.handlestringnullable

Always included.

watchNextVideos.channel.idstringnullable

Always included.

watchNextVideos.publishedTimeTextstringnullable

Always included.

watchNextVideos.publishedTimestringnullable

Always included.

watchNextVideos.publishDateTextstringnullable

Always included.

watchNextVideos.publishDatestringnullable

Always included.

watchNextVideos.viewCountTextstringnullableoptional

Optional.

watchNextVideos.viewCountIntintegernullable

Always included.

watchNextVideos.lengthTextstringnullableoptional

Optional.

watchNextVideos.lengthInSecondsintegernullableoptional

Optional.

watchNextVideos.videoUrlstring

Always included.

absolute HTTPS URL

thumbnailstring

https://img.youtube.com/vi/<id>/maxresdefault.jpg.

absolute HTTPS URL

publishDatestringnullable

Publish timestamp with the channel's UTC offset, from the page metadata.

keywordsstring[]

Video keywords (tags) as published; empty when none.

up to 500 items

genrestringnullable

YouTube category ("Music", "Entertainment").

durationMsintegernullable

Published duration in milliseconds (the microformat length).

durationFormattedstringnullable

Duration as HH:MM:SS.

Caption tracks the web player lists: baseUrl, name.simpleText, vssId, languageCode, kind (asr for auto-generated), isTranslatable, trackName. URLs are returned as data and expire; use the transcript operation to read one.

up to 100 items

captionTracks.baseUrlstring

Always included.

absolute HTTPS URL

Always included.

captionTracks.name.simpleTextstring

Always included.

captionTracks.vssIdstring

Always included.

captionTracks.languageCodestring

Always included.

captionTracks.kindstringoptional

Optional.

captionTracks.isTranslatablebooleanoptional

Optional.

captionTracks.trackNamestringoptional

Optional.

Muxed audio+video formats the web player exposes, or null: expiresInSeconds, hlsManifestUrl, dashManifestUrl, formats (itag, url, cdnUrl, expiresAt, mimeType, codecs, bitrate, width, height, quality, qualityLabel, fps, audioQuality, audioSampleRate, audioChannels, approxDurationMs, projectionType, hasVideo, hasAudio, requiresSignatureDecipher and signatureCipher {url, signature, signatureParameter, expiresAt} when the URL is ciphered) and a note. Nothing is downloaded.

downloadOptions.expiresInSecondsstringnullable

Always included.

downloadOptions.hlsManifestUrlstringnullable

Always included.

downloadOptions.dashManifestUrlstringnullable

Always included.

up to 50 items

downloadOptions.formats.itaginteger

Always included.

downloadOptions.formats.urlstringnullable

Always included.

downloadOptions.formats.cdnUrlstringnullable

Always included.

downloadOptions.formats.expiresAtstringnullable

Always included.

downloadOptions.formats.mimeTypestringnullable

Always included.

downloadOptions.formats.codecsstringnullable

Always included.

downloadOptions.formats.bitrateintegernullable

Always included.

downloadOptions.formats.widthintegernullable

Always included.

downloadOptions.formats.heightintegernullable

Always included.

downloadOptions.formats.qualitystringnullable

Always included.

downloadOptions.formats.qualityLabelstringnullable

Always included.

downloadOptions.formats.fpsintegernullable

Always included.

downloadOptions.formats.audioQualitystringnullable

Always included.

downloadOptions.formats.audioSampleRatestringnullable

Always included.

downloadOptions.formats.audioChannelsintegernullable

Always included.

downloadOptions.formats.approxDurationMsstringnullable

Always included.

downloadOptions.formats.projectionTypestringnullable

Always included.

downloadOptions.formats.hasVideoboolean

Always included.

downloadOptions.formats.hasAudioboolean

Always included.

downloadOptions.formats.requiresSignatureDecipherboolean

Always included.

Optional.

downloadOptions.formats.signatureCipher.urlstringnullable

Always included.

downloadOptions.formats.signatureCipher.signaturestringnullable

Always included.

downloadOptions.formats.signatureCipher.signatureParameterstringnullable

Always included.

downloadOptions.formats.signatureCipher.expiresAtstringnullable

Always included.

downloadOptions.notestring

Always included.

YouTube's public Most replayed graph, or null: markers (startMillis, durationMillis, intensityScoreNormalized) and ranges (visibleTimeRangeStartMillis, visibleTimeRangeEndMillis, decorationTimeMillis, label).

Always included.

up to 1000 items

most_replayed.markers.startMillisinteger

Always included.

≥ 0

most_replayed.markers.durationMillisinteger

Always included.

≥ 0

most_replayed.markers.intensityScoreNormalizednumber

Always included.

up to 100 items

most_replayed.ranges.visibleTimeRangeStartMillisinteger

Always included.

≥ 0

most_replayed.ranges.visibleTimeRangeEndMillisinteger

Always included.

≥ 0

most_replayed.ranges.decorationTimeMillisinteger

Always included.

≥ 0

most_replayed.ranges.labelstringnullable

Always included.

isPaidPromotionboolean

True when the player shows the "Includes paid promotion" disclosure.

sourceUrlstring

Public YouTube URL the operation represents (page or API route).

absolute HTTPS URL

fetchedAtstring

UTC retrieval timestamp.

source is public_page; no warnings are defined for this operation.

coverage.sourceenum

Always included.

one of: public_page, public_api

coverage.completeboolean

Always included.

coverage.warningsenum[]

Always included.

up to 8 items

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes

HTTP	failure.code	Meaning
400	`invalid_request`	Missing, malformed, duplicate or conflicting parameters, unsupported parameters or an unsafe URL.
400	`invalid_continuation`	YouTube rejected the supplied continuation token.
401	`unauthorized`	Missing or invalid worker API key.
403	`restricted_page`	The channel, video, playlist or post is terminated, private, members-only or otherwise unavailable.
403	`age_restricted`	The video is age restricted and cannot be read logged out.
404	`not_found`	YouTube reports no channel, video, playlist or post for the identifier.
429	`upstream_rate_limited`	YouTube rate limited the request; no automatic retry.
502	`upstream_challenged`	YouTube rejected or challenged the request.
502	`unsupported_page`	The response lacks the embedded data, the data is malformed, or the resolved identity does not match the request.
502	`response_too_large` `payload_too_complex`	The response exceeded byte, depth or node limits.
502	`unsafe_redirect` `request_limit` `upstream_error`	The bounded request could not complete.
503	`busy`	All worker slots are in use.
504	`timeout`	The total retrieval deadline expired.

Code example

curl "https://api.scrapeatlas.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVid0000001a" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.scrapeatlas.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVid0000001a",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data.status, data);

type Result = {
  status: "success" | "partial" | "failed" | "challenged";
  requestId: string;
  [field: string]: unknown;
};

const response = await fetch(
  "https://api.scrapeatlas.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVid0000001a",
  {
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!
    }
  }
);

const data = (await response.json()) as Result;
if (data.status === "failed" || data.status === "challenged") {
  throw new Error(`YouTube request failed: ${data.requestId}`);
}
console.log(data);

import requests

response = requests.get(
    "https://api.scrapeatlas.com/v1/youtube/video",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "url": "https://www.youtube.com/watch?v=Vid0000001a"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.scrapeatlas.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVid0000001a", nil)
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data["status"], data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.scrapeatlas.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVid0000001a"))
            .GET()
            .header("x-api-key", "YOUR_API_KEY")
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Use your sa_live_… customer key at https://api.scrapeatlas.com.

Responses

Successful result. Synthetic example validated against the runtime contract.

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000016",
  "type": "video",
  "id": "Vid0000001a",
  "title": "Synthetic video one",
  "description": "Synthetic description.\n\nChapters:\n0:00 Intro\n3:54 Main part\n\nSponsored by ExampleBrand: https://examplebrand.test/offer",
  "descriptionLinks": [
    "https://www.youtube.com/watch?v=Vid0000001a",
    "https://www.youtube.com/watch?v=Vid0000001a&t=234s",
    "https://examplebrand.test/offer"
  ],
  "commentCountText": "2.4M",
  "commentCountInt": 2400000,
  "likeCountText": "19385119",
  "likeCountInt": 19385119,
  "viewCountText": "1,814,741,641",
  "viewCountInt": 1814741641,
  "publishDateText": "Oct 24, 2009",
  "collaborators": [],
  "channel": {
    "id": "UCsynthetic0000000000001",
    "url": "https://www.youtube.com/@ExampleChannel",
    "handle": "ExampleChannel",
    "title": "Example Channel",
    "thumbnail": "https://yt3.example.test/avatar=s48-c-k-c0x00ffffff-no-rj"
  },
  "chapters": [
    {
      "title": "Intro",
      "timeDescription": "0:00",
      "startSeconds": 0
    },
    {
      "title": "Main part",
      "timeDescription": "3:54",
      "startSeconds": 234
    }
  ],
  "watchNextVideos": [
    {
      "id": "Vid0000002b",
      "title": "Synthetic related video",
      "thumbnail": "https://i.ytimg.com/vi/Vid0000002b/hq720.jpg?sqp=synthetic",
      "channel": {
        "title": "Another Channel",
        "url": "https://www.youtube.com/@AnotherChannel",
        "handle": "AnotherChannel",
        "id": "UCsynthetic0000000000002"
      },
      "publishedTimeText": "11 months ago",
      "publishedTime": "2025-10-12T12:00:00.000Z",
      "publishDateText": "11 months ago",
      "publishDate": "2025-10-12T12:00:00.000Z",
      "viewCountText": "1.8M",
      "viewCountInt": 1800000,
      "lengthText": "18:01",
      "lengthInSeconds": 1081,
      "videoUrl": "https://www.youtube.com/watch?v=Vid0000002b"
    },
    {
      "id": "Vid0000003c",
      "title": "Synthetic live related stream",
      "thumbnail": "https://i.ytimg.com/vi/Vid0000003c/hq720.jpg?sqp=synthetic",
      "channel": {
        "title": "Another Channel",
        "url": "https://www.youtube.com/@AnotherChannel",
        "handle": "AnotherChannel",
        "id": "UCsynthetic0000000000002"
      },
      "publishedTimeText": "Streamed 1 day ago",
      "publishedTime": null,
      "publishDateText": "Streamed 1 day ago",
      "publishDate": null,
      "viewCountInt": null,
      "videoUrl": "https://www.youtube.com/watch?v=Vid0000003c"
    }
  ],
  "thumbnail": "https://img.youtube.com/vi/Vid0000001a/maxresdefault.jpg",
  "publishDate": "2009-10-24T23:57:33-07:00",
  "keywords": [
    "synthetic",
    "example"
  ],
  "genre": "Music",
  "durationMs": 214000,
  "durationFormatted": "00:03:34",
  "captionTracks": [
    {
      "baseUrl": "https://www.youtube.com/api/timedtext?v=Vid0000001a&lang=en&signature=synthetic",
      "name": {
        "simpleText": "English"
      },
      "vssId": ".en",
      "languageCode": "en",
      "isTranslatable": true,
      "trackName": ""
    },
    {
      "baseUrl": "https://www.youtube.com/api/timedtext?v=Vid0000001a&kind=asr&lang=en&signature=synthetic",
      "name": {
        "simpleText": "English (auto-generated)"
      },
      "vssId": "a.en",
      "languageCode": "en",
      "kind": "asr",
      "isTranslatable": true,
      "trackName": ""
    }
  ],
  "downloadOptions": {
    "expiresInSeconds": "21540",
    "hlsManifestUrl": null,
    "dashManifestUrl": null,
    "formats": [
      {
        "itag": 18,
        "url": null,
        "cdnUrl": "https://rr1---sn-synthetic.googlevideo.com/videoplayback?expire=1789220330&itag=18&mime=video%2Fmp4",
        "expiresAt": "2026-09-12T13:38:50.000Z",
        "mimeType": "video/mp4; codecs=\"avc1.42001E, mp4a.40.2\"",
        "codecs": "avc1.42001E, mp4a.40.2",
        "bitrate": 444226,
        "width": 640,
        "height": 360,
        "quality": "medium",
        "qualityLabel": "360p",
        "fps": 25,
        "audioQuality": "AUDIO_QUALITY_LOW",
        "audioSampleRate": "44100",
        "audioChannels": 2,
        "approxDurationMs": "213089",
        "projectionType": "RECTANGULAR",
        "hasVideo": true,
        "hasAudio": true,
        "requiresSignatureDecipher": true,
        "signatureCipher": {
          "url": "https://rr1---sn-synthetic.googlevideo.com/videoplayback?expire=1789220330&itag=18&mime=video%2Fmp4",
          "signature": "SYNTHETICSIGNATURE",
          "signatureParameter": "sig",
          "expiresAt": "2026-09-12T13:38:50.000Z"
        }
      }
    ],
    "note": "These are YouTube's muxed audio+video formats when exposed. Links can expire, and some videos may only expose signature-ciphered URLs."
  },
  "most_replayed": {
    "markers": [
      {
        "startMillis": 0,
        "durationMillis": 2140,
        "intensityScoreNormalized": 1
      },
      {
        "startMillis": 2140,
        "durationMillis": 2140,
        "intensityScoreNormalized": 0.42
      }
    ],
    "ranges": [
      {
        "visibleTimeRangeStartMillis": 0,
        "visibleTimeRangeEndMillis": 6420,
        "decorationTimeMillis": 2140,
        "label": "Most replayed"
      }
    ]
  },
  "isPaidPromotion": true,
  "sourceUrl": "https://www.youtube.com/watch?v=Vid0000001a",
  "fetchedAt": "2026-09-12T12:00:00.000Z",
  "coverage": {
    "source": "public_page",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 320000,
    "durationMs": 900
  }
}

Missing, malformed, duplicate or conflicting parameters, unsupported parameters or an unsafe URL. YouTube rejected the supplied continuation token.

{
  "requestId": "9d2f1c0a-6b1e-4c7d-9a8e-2f3b4c5d6e7f",
  "accounting": {
    "upstreamRequests": 0,
    "responseBytes": 0,
    "durationMs": 0
  },
  "success": false,
  "status": "failed",
  "failure": {
    "code": "invalid_request",
    "message": "Invalid request: missing, duplicate, unsupported or malformed parameters."
  }
}