> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube

> Scrape a YouTube video link for its title, channel, date, length, views, likes and description, and get its audio as M4A or its video as MP4.

Send a YouTube video link to Scrape and `markdown` returns a short document about the video: its title, channel, publish date, length, views, likes and description. Add `audio` or `video` to also get the file.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request reads a video and asks for its audio.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "formats": ["markdown", "audio"]
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    formats: ["markdown", "audio"],
  }),
});
const { data } = await response.json();
console.log(data.markdown);
console.log(data.audio);
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "formats": ["markdown", "audio"],
    },
)
data = response.json()["data"]
print(data["markdown"])
print(data["audio"])
```

## Read the response

`markdown` is the video document. `audio` is a link to an M4A file that works for 1 hour. This real response is cut: the description and the link are shortened.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "# Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)\n\n[Rick Astley](https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw) · Published 2009-10-25 · Length 3:33 · 1,838,183,196 views · 19,509,472 likes\n\nThe official video for “Never Gonna Give You Up” by Rick Astley. …",
    "audio": "https://…/media/561cef5b-e737-4523-adc7-7c182f03179c.m4a?…",
    "metadata": {
      "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
      "ogImage": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "sourceURL": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "statusCode": 200,
      "contentType": "text/markdown",
      "cacheState": "miss",
      "scrapeId": "c9e9e5c0-4647-4807-8aeb-d587db57567d",
      "costUsd": 0.001
    }
  },
  "id": "c9e9e5c0-4647-4807-8aeb-d587db57567d",
  "costUsd": 0.001,
  "requestId": "c9e9e5c0-4647-4807-8aeb-d587db57567d"
}
```

`metadata.title`, `description` and `ogImage` come from the video. To keep the audio, download it within the hour.

## Options

| Format | What you get |
| - | - |
| `markdown` | The video document: title, channel, publish date, length, views, likes and description. |
| `summary`, `json` | A summary or fields in your own shape, made from that document. See [Summary](https://docs.stophy.dev/scrape/summary.md) and [JSON](https://docs.stophy.dev/scrape/json.md). |
| `audio` | A link to the audio as an M4A file, in the best quality available. The link works for 1 hour. |
| `video` | A link to the video as an MP4 file with sound, in the best single-file quality available. The link works for 1 hour. |

Supported links are `watch?v=`, `youtu.be/`, `/shorts/`, `/embed/` and `/live/` URLs, on `youtube.com`, `www.youtube.com`, `m.youtube.com` and `music.youtube.com`.

## More from a video

A scrape returns the document above, not the transcript, the comments or the channel. For those, use the YouTube parsers, which return a video's transcript, comments, channel, playlist and search results as data. See [Pre-built parsers](https://docs.stophy.dev/scrape/prebuilt-parsers).

## Limits and errors

* `audio` and `video` need an API key. Without one, the call returns `401 apiKeyRequired`.
* `audio` and `video` work only for a YouTube video link. Any other URL returns `400 invalidRequest` with a message that starts `formats: audio and video are available for YouTube video links`.
* An audio file larger than 40 MB, or a video file larger than 100 MB, returns `400 invalidRequest` and says what to send instead.
* `audio` and `video` with `zeroDataRetention` return `400 invalidRequest`, because the file is kept for an hour.
* If YouTube does not provide a video's file, the call fails with `503 sourceUnavailable`. Nothing is charged, and you can retry.

## Price

\$1 per 1,000 videos. `audio` and `video` add nothing to the price.

## Related

* [Pre-built parsers](https://docs.stophy.dev/scrape/prebuilt-parsers) read a video's transcript, comments and channel.
* [Markdown](https://docs.stophy.dev/scrape/markdown.md) is the format that returns the video document.
* [Summary](https://docs.stophy.dev/scrape/summary.md) summarizes the video document.
* [Scrape overview](https://docs.stophy.dev/scrape/overview) lists every format and option.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.