Use YouTube SponsorBlock Segments Scraper with Python

Get community-reported SponsorBlock segments for any YouTube video: sponsor reads, intros, outros, self-promos, filler, highlights, and more, with start/end times and votes.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "categories": [
    "sponsor",
    "intro"
  ],
  "concurrency": 4,
  "includeDescriptions": true,
  "includeHiddenSegments": false,
  "includeSubmitterInfo": true,
  "includeSummary": false,
  "includeYouTubeMetadata": true,
  "maxSegmentsPerVideo": 0,
  "minVotes": 0,
  "source": "visible",
  "videoUrls": [
    "https://www.youtube.com/watch?v=7wtfhZwyrcc"
  ]
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`videoUrls`	array	required	YouTube video URLs or 11-character video IDs. Accepts watch, youtu.be, Shorts, live, embed, and music links. Add multiple videos for a batch.
`categories`	array	optional	Only return these SponsorBlock categories. Leave empty to include every category.
`actionTypes`	array	optional	Only return segments whose action matches one of these. Leave empty to include every action.
`source`	string	optional	Use 'Visible segments' for the segments SponsorBlock currently acts on. Use 'All submissions' to include hidden and disputed submissions from the search database.
`minVotes`	integer	optional	Drop segments with fewer community votes than this. Use -2 to include every submission, 0 to drop downvoted ones, or a higher value to keep only well-confirmed segments.
`includeHiddenSegments`	boolean	optional	When the source is 'All submissions', also return segments hidden by moderation or a shadowbanned submitter.
`includeDescriptions`	boolean	optional	Include the community-written note attached to a segment when one exists.
`includeSubmitterInfo`	boolean	optional	Resolve each segment's public SponsorBlock submitter ID to a username and aggregate stats when available. Never exposes private IDs.
`includeYouTubeMetadata`	boolean	optional	Add the video title, channel name/URL/ID, thumbnail, YouTube duration, view count, publish date, and live status from YouTube's public oEmbed and player endpoints.
`includeSummary`	boolean	optional	Add one per-video summary row (segment count, total seconds, category/action breakdown) and one run summary row.
`maxSegmentsPerVideo`	integer	optional	Keep at most this many segments per video after filtering and sorting by start time. Use 0 for no limit.
`concurrency`	integer	optional	How many videos to process at the same time. Higher is faster but can trigger rate limits.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/BEU5z7tj6h8MNRtJO/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

SponsorBlock segment rows, per-video/run summaries, and truthful per-video status rows.

Questions before you run

Which inputs are required?

The published required fields are videoUrls

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build DHJ6AF7rUGBo2bUjK and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.