Getting a Video's Description, Chapters, and Tags

A video's description, tags, and any links the creator dropped in come back with include_metadata=true — no separate request needed. Chapters are a bit different: YouTube doesn't expose them as a structured field, so they live inside the description text as timestamp lines, and you parse them out yourself.

This is a common point of confusion: people expect a chapters array sitting alongside title and tags, the way YouTube's own watch page displays a chapter scrubber. That scrubber is YouTube rendering the description's timestamp lines for you in the UI — the underlying data is still just text.

What include_metadata gives you

curl -s "https://scriptube.me/api/v1/transcripts/BATCH_ID?include_metadata=true" \
  -H "X-API-Key: YOUR_API_KEY"

Links in the description (a creator's site, socials, affiliate links) come through as plain text inside description — there's no separate structured field for them, so extract URLs with a regex if you need them isolated:

import re
URL_RE = re.compile(r"https?://\S+")
links = URL_RE.findall(item.get("description") or "")

topic_categories is a different thing entirely — it's YouTube's own topical classification for the video (drawn from Wikipedia topic IDs), not anything the creator wrote. It's useful for a rough "what is this video about" signal without reading the description at all, though it's coarser than tags.

Chapters: parsing them from the description

YouTube chapters are just description lines that follow a timestamp pattern (0:00 Intro, 12:34 Big topic). Scriptube stores the description as-is — raw text, chapter lines included — rather than parsing it into a structured chapter list. That raw description is available via include_metadata on the API, and in the description column of the CSV, JSON, and JSONL exports. Parsing the "0:00 Title" lines out of it yourself is a small regex:

import re
import requests

HEADERS = {"X-API-Key": "YOUR_API_KEY"}
BASE = "https://scriptube.me"
batch_id = "00000000-0000-0000-0000-000000000000"

page = requests.get(
    f"{BASE}/api/v1/transcripts/{batch_id}",
    headers=HEADERS,
    params={"include_metadata": "true"},
).json()

TIMESTAMP_LINE = re.compile(r"^\s*(?:\d+:)?\d{1,2}:\d{2}\s+(.+)$")

def chapters_from_description(description: str):
    chapters = []
    for line in (description or "").splitlines():
        m = TIMESTAMP_LINE.match(line)
        if m:
            chapters.append(line.strip())
    return chapters

for item in page["items"]:
    print(item["title"], "->", chapters_from_description(item.get("description")))

This catches both mm:ss and h:mm:ss timestamp formats. It's a text heuristic, not a guarantee — a description with an unrelated line that happens to start with something like 1:30 will be picked up too, so sanity-check results on content you don't fully control, especially if you're running this across a large, varied channel batch rather than one video you've looked at by hand.

Turning chapters into something useful

Once you have the timestamp lines, you can line them up against the transcript's own timed segments (include_segments=true) to pull the transcript text for each chapter specifically, instead of just the chapter title. That's the basis of building structured, timestamped notes from a video — see building show notes from chapters for the full walkthrough.

The rough shape of that combination: parse chapter start times from the description as above, convert each mm:ss or h:mm:ss string into seconds, then collect every segment whose start falls between one chapter's start and the next's. The result is a chapter title paired with the actual spoken text under it — useful for a table of contents that links straight to relevant transcript excerpts, not just timestamps.

Other metadata worth knowing about

include_metadata also returns fields that aren't description-related but are easy to overlook: made_for_kids and privacy_status tell you whether a video is restricted in ways that might affect what you can do with the output, and thumbnail_url is useful if you're building any kind of visual index alongside the text. None of these require a separate call — they all come back on the same batch read.

How to do it in the dashboard

Open a video's detail page after processing — the description (chapters included, as raw text) is shown under the transcript, alongside tags and the other metadata fields. There's no chapter-specific view yet; copy the description if you need to parse chapters outside the API.

Frequently asked

Does Scriptube return structured chapters directly? No — chapters aren't a separate field. They come back as part of the raw description text, via include_metadata or the description column in CSV/JSON/JSONL exports. The regex above parses the "0:00 Title" lines out of that text yourself, and it's a reasonable approach since YouTube's own chapter format is simple and consistent.

Does category_id tell me the category name, like "Education" or "Music"? No — it's YouTube's raw numeric id. There's no lookup table exposed for turning it into a readable name today; topic_categories is usually the more useful field if you want a human-readable sense of subject matter.

Do I need include_segments as well as include_metadata for any of this? Only if you plan to pull the actual transcript text for each chapter, not just the chapter titles and timestamps — include_metadata alone gets you the description and tags.

Does this work the same way for a whole channel batch, not just one video? Yes — include_metadata=true applies per item regardless of whether the batch is a single video, a playlist, or a channel, so the same chapter-parsing code works unchanged across any of them.

Next steps

• Building show notes from chapters — combining this with timed segments.
• Every way to get timestamps — segments, SRT/VTT, and the UI.

Pull metadata on your own videos: sign up free.