YouTube Video Description: Chapter & Timestamp Checker

For video editors, channel managers and agencies checking public YouTube descriptions for missing or invalid manual chapter timestamps.

About $0.01 per complete video check. Ten complete checks cost about $0.10, plus a $0.00005 run start at the default memory setting. The default example checks one video. Bronze, Silver and Gold discounts apply. Incomplete checks, unavailable videos, invalid inputs, duplicate videos and the run summary carry no video-check fee.

Give the Actor a public video URL or ID. It fetches the description, obtains the duration when needed, and returns a plain-English verdict before the supporting fields. You do not need a YouTube login, account cookies or a YouTube API key. An Apify token is needed only when you call the Actor through the Apify API.

A passing result means the visible manual timestamp list meets the checks described below. It does not guarantee that YouTube displays chapters: channel feature access, creator settings and automatic chapter eligibility are separate.

What you get

Field	Meaning
verdict	The answer to read first, such as a passing manual chapter list or a missing manual list.
status	Stable machine-readable outcome for filters and automations.
complete	Whether the source and checks were sufficient for a complete video check. Only complete video checks carry the unit fee.
title	Public title observed for the requested video.
videoUrl, videoId	Canonical watch URL and eleven-character case-sensitive video ID.
manualTimestampCount	Number of recognized timestamp entries in the description.
timestamps	Original timestamp text, computed seconds, label, description line number and component-validity flag.
durationSeconds	Public source duration, or null when it could not be read.
failedRules	Specific rule codes for the detected problems.
description	Fetched public description text used for the check, including line breaks.
descriptionPresent	Distinguishes a source-provided empty description from an absent field.
descriptionSource, durationSource	Source field paths explaining where the description and duration came from.
observedAt	UTC observation timestamp.
sourceRoute, sourceAttempts	Signed-out source route and number of attempts for this video.
chapterScope	Always manual_description_only.
displayEligibilityChecked	Always false; private feature eligibility is outside this check.
recordType, resultId	Distinguish video-check rows from free input notes and provide a stable result key within the run.

The dataset view puts the verdict, video, timestamp count, duration and completion state together. The key-value store contains a free SUMMARY record and a self-contained HTML REPORT that groups results by video. The output links take you directly to these records.

Start in three steps

1. Keep the prefilled example or paste a public YouTube URL into query. A bare eleven-character video ID also works.
2. Set an Apify maximum charge if you want a spending limit, then start the run. The prefill checks one video rather than crawling a channel.
3. Open the Chapter checks dataset view, read verdict, and filter incomplete results separately. Use the report for a readable review or download JSON for all timestamp entries.

To check several videos, leave query empty and supply videoUrls. When calling the API, omit unused fields. If you keep a query and also supply a list, both are included and duplicate canonical IDs are checked once.

Input reference

Input	Type and default	How to use it
query	Optional string; one example is prefilled in the Console	Public watch, Shorts or live URL, video ID, or explicit channel handle such as @3blue1brown.
videoUrls	Optional array	Public video URLs or IDs. Tracking parameters and timestamp fragments do not create new videos.
channels	Optional array	Public channel handles or channel URLs. Channel mode is used only when you explicitly provide a channel.
maxVideosPerChannel	Integer, default 5, maximum 100	Maximum eligible uploads selected from each supplied channel.
maxVideos	Integer, default 100, maximum 1,000	Run-wide cap on unique videos after canonical deduplication.
urls	Optional array	Alias accepted for integrations that use a general URL list.
startUrls	Optional array	Request-list alias; each item may contain a url property.

An omitted input uses the one-video example. Explicit empty input lists produce a free empty summary. An invalid video ID produces an input-note row before any video fetch. URLs from lookalike domains are rejected. Video IDs are case-sensitive; the Actor does not lowercase them.

Channel mode samples the available public upload listing, excluding identified upcoming, private, members-only and live entries. It does not crawl the full channel history. An unresolved channel produces a free note.

{
  "videoUrls": [
    "https://www.youtube.com/watch?v=aircAruvnKk",
    "https://youtu.be/rfscVS0vtbw"
  ],
  "maxVideos": 2
}

What the chapter checks mean

YouTube's published manual chapter guidance calls for a list of timestamps and titles beginning at zero, at least three entries in ascending order, and chapters at least ten seconds long. This Actor checks those conditions against the public description and the observed duration. It also checks valid minute/second components and whether any timestamp reaches or exceeds the video length.

Recognized entries begin a description line with a timestamp, optionally preceded by punctuation or an emoji. Common forms include 0:00 Introduction, (00:00) Introduction, 00:00 - Introduction, and 1:02:03 Introduction. Labels may contain non-English text. The original label and timestamp are preserved. Total minutes and multi-hour times are handled without a fixed one-hour limit.

An unsupported list layout is not treated as proof that chapters are missing. For example, a list with the title before the time or full-width timestamp punctuation can return ambiguous_format. Mixed formats inside a chapter block also remain incomplete. An isolated prose timestamp outside a recognized block, such as a separate correction note, is not added as a chapter. These rules reduce false missing-list and false descending-order findings, but unusual free-form descriptions can still need manual review.

Status	Meaning and unit fee
valid_manual_chapters	Recognized list passes all checks, including the final segment. Complete check.
invalid_manual_chapters	Description and required duration were available; one or more rules failed. Complete check.
missing_manual_chapters	Available description contains no recognized or ambiguous timestamp list. Complete check.
unknown_description	The description field was absent. Incomplete and free.
unknown_duration	A list was found but duration needed for final validation was unavailable. Incomplete and free.
ambiguous_format	Timestamp-like content needs manual interpretation. Incomplete and free.
source_unavailable, video_unavailable	Source could not support a complete public check. Incomplete and free.
invalid_input, channel_unavailable	Input or channel note. No video-check fee.

Failed rules include first_timestamp_not_zero, fewer_than_three_chapters, not_strictly_ascending, invalid_time_component, missing_chapter_title, chapter_under_ten_seconds, timestamp_at_or_beyond_duration, and final_chapter_under_ten_seconds. A missing duration is never replaced with a historical cached seed. An explicitly empty description can support a missing-list result; an absent description cannot.

Pricing and spending limits

Complete checks	Standard price including default run start	Bronze price including default run start
1	$0.01005	$0.00955
10	$0.10005	$0.09505
100	$1.00005	$0.95005

The unit price is $0.01 on Free, $0.0095 on Bronze, $0.009 on Silver and $0.008 on Gold and higher tiers. The default start is $0.00005; Apify can multiply its start event for larger memory allocations. Keep the default memory unless your workload needs more. The displayed run maximum is authoritative for your plan and settings.

Each complete unique video result is saved before its fee is requested. A missing manual list is a useful complete check, as is a list with specific formatting failures. Source errors and incomplete findings do not consume video-check units. Apify's small run start still applies to runs that return only free notes. The Actor stops when another complete check cannot fit under your maximum charge.

Deduplication applies within one run, including equivalent watch, short-link, live and Shorts URLs. A new run is a fresh observation and may charge again. Restart recovery within the same run restores saved source evidence, final rows and acknowledged charges so completed work is not emitted or charged again.

Use with the API

Use your own Apify token in an environment variable. Do not paste credentials into Actor input. The following request starts the same one-video workflow used by the prefill:

curl --request POST \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"query":"https://www.youtube.com/watch?v=aircAruvnKk"}' \
  'https://api.apify.com/v2/acts/moggedhq~youtube-video-description-chapter-checker/run-sync-get-dataset-items?format=json'

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("moggedhq/youtube-video-description-chapter-checker").call(
    run_input={"videoUrls": ["aircAruvnKk", "rfscVS0vtbw"], "maxVideos": 2}
)
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["verdict"], row.get("videoUrl"))

Use with AI agents (MCP)

Connect your agent to https://mcp.apify.com. Describe the actual job: fetch public YouTube video descriptions and check their manual chapter timestamps against duration. Supply the video URLs and a maximum charge. Ask the agent to preserve incomplete results and report failed rule codes rather than silently dropping them.

Ask: “Check these public YouTube video descriptions for missing or invalid chapter timestamps. Return the verdict, timestamp labels, duration and failed rules for each video. Keep incomplete checks separate.” No separate model key is required.

Limits and source observations

Public signed-out access varies by video and source conditions. Requests are serial and paced, with fresh datacenter retries and a bounded mobile residential fallback. There is no login, cookie import, CAPTCHA solving or paid upstream data API. Videos requiring private account access cannot be checked by this workflow.

This is a snapshot, not a permanent guarantee. Descriptions can change after observation. Automatic chapters, player-display confirmation, copyright restrictions, monetization, strikes and channel feature access are outside scope. Live broadcasts may lack a final duration.

Tested output

A private cloud validation on 15 October 2026 returned 32 complete checks from 32 distinct public videos in 189 seconds. The set included all six chapter-positive discovery examples, Shorts, non-English descriptions, explicit empty descriptions and long courses. Ten returned rows were checked against the fetched text and source duration. This small test set is evidence of that run, not a promise that every future video will be available.

One real result from that run:

{"verdict":"Chapters OK on 'Learn Python - Full Course for Beginners [Tutorial]': 35 chapters from 0:00, in order, each at least 10 seconds.","videoId":"rfscVS0vtbw","manualTimestampCount":35,"durationSeconds":16012,"complete":true,"sourceRoute":"desktop_datacenter"}

FAQ

Does a valid result guarantee chapters appear on YouTube? No. It confirms the visible formatting and timing rules tested here. Settings and eligibility can still prevent display.

Can a video without manual chapters have automatic chapters? Yes. The missing-list verdict concerns the description only and does not assert that the player has no chapters.

Why is an invalid list charged? It is a complete check with specific problems you can correct. An unresolved source or ambiguous list is free.

Why is an empty description different from a missing field? An explicit empty source value supports a missing-list conclusion. An absent field supplies no evidence about the description, so the check remains incomplete.

Can I supply a description directly? No. This Actor fetches the public video and the duration required for validation. It is not a supplied-text calculator.

Are repeated URLs charged repeatedly? Equivalent IDs in one run are deduplicated. Running a new job checks a fresh snapshot and is a new billable observation when complete.

Can I check Shorts or long courses? Yes, using their public URL or ID. Short videos often have no manual list. The same stated timestamp rules are applied without inventing chapters.

What should I do with an incomplete result? Inspect the status and source fields. Try a later run for a transient source refusal, or review the description manually for an unsupported layout.

What are the authoritative chapter rules? See YouTube's Video Chapters help. Use this tool only where your collection and use of public data are permitted.