YouTube SponsorBlock Segments Scraper

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.

Open on Apify GitHub source

Input schema

Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.

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.

Show all input fields

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.

Download the published input schema

View complete JSON

{
  "properties": {
    "actionTypes": {
      "default": [],
      "description": "Only return segments whose action matches one of these. Leave empty to include every action.",
      "editor": "select",
      "items": {
        "enum": [
          "skip",
          "mute",
          "full",
          "poi",
          "chapter"
        ],
        "enumTitles": [
          "Skip",
          "Mute",
          "Full video",
          "Highlight/POI",
          "Chapter"
        ],
        "type": "string"
      },
      "title": "Action types",
      "type": "array"
    },
    "categories": {
      "default": [],
      "description": "Only return these SponsorBlock categories. Leave empty to include every category.",
      "editor": "select",
      "items": {
        "enum": [
          "sponsor",
          "selfpromo",
          "interaction",
          "intro",
          "outro",
          "preview",
          "hook",
          "music_offtopic",
          "filler",
          "poi_highlight",
          "exclusive_access",
          "chapter"
        ],
        "enumTitles": [
          "Sponsor",
          "Unpaid/Self Promotion",
          "Interaction Reminder",
          "Intro",
          "Outro",
          "Preview/Recap",
          "Hook",
          "Non-Music Section",
          "Filler Tangent",
          "Highlight",
          "Exclusive Access",
          "Chapter"
        ],
        "type": "string"
      },
      "prefill": [
        "sponsor",
        "intro"
      ],
      "title": "Segment categories",
      "type": "array"
    },
    "concurrency": {
      "default": 4,
      "description": "How many videos to process at the same time. Higher is faster but can trigger rate limits.",
      "maximum": 10,
      "minimum": 1,
      "prefill": 4,
      "title": "Simultaneous videos",
      "type": "integer"
    },
    "includeDescriptions": {
      "default": true,
      "description": "Include the community-written note attached to a segment when one exists.",
      "prefill": true,
      "title": "Include segment descriptions",
      "type": "boolean"
    },
    "includeHiddenSegments": {
      "default": false,
      "description": "When the source is 'All submissions', also return segments hidden by moderation or a shadowbanned submitter.",
      "prefill": false,
      "title": "Include hidden submissions",
      "type": "boolean"
    },
    "includeSubmitterInfo": {
      "default": true,
      "description": "Resolve each segment's public SponsorBlock submitter ID to a username and aggregate stats when available. Never exposes private IDs.",
      "prefill": true,
      "title": "Include public submitter info",
      "type": "boolean"
    },
    "includeSummary": {
      "default": false,
      "description": "Add one per-video summary row (segment count, total seconds, category/action breakdown) and one run summary row.",
      "prefill": false,
      "title": "Include summary rows",
      "type": "boolean"
    },
    "includeYouTubeMetadata": {
      "default": true,
      "description": "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.",
      "prefill": true,
      "title": "Include YouTube metadata",
      "type": "boolean"
    },
    "maxSegmentsPerVideo": {
      "default": 0,
      "description": "Keep at most this many segments per video after filtering and sorting by start time. Use 0 for no limit.",
      "maximum": 1000000,
      "minimum": 0,
      "prefill": 0,
      "title": "Maximum segments per video",
      "type": "integer"
    },
    "minVotes": {
      "default": 0,
      "description": "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.",
      "maximum": 1000000,
      "minimum": -2,
      "prefill": 0,
      "title": "Minimum votes",
      "type": "integer"
    },
    "source": {
      "default": "visible",
      "description": "Use 'Visible segments' for the segments SponsorBlock currently acts on. Use 'All submissions' to include hidden and disputed submissions from the search database.",
      "editor": "select",
      "enum": [
        "visible",
        "all"
      ],
      "enumTitles": [
        "Visible segments",
        "All submissions (includes hidden)"
      ],
      "prefill": "visible",
      "title": "Segment source",
      "type": "string"
    },
    "videoUrls": {
      "description": "YouTube video URLs or 11-character video IDs. Accepts watch, youtu.be, Shorts, live, embed, and music links. Add multiple videos for a batch.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "prefill": [
        "https://www.youtube.com/watch?v=7wtfhZwyrcc"
      ],
      "title": "Video URLs or IDs",
      "type": "array"
    }
  },
  "required": [
    "videoUrls"
  ],
  "schemaVersion": 1,
  "title": "YouTube SponsorBlock Segments Scraper",
  "type": "object"
}

Output schema

Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.

Field	Type	Required	Description
`segments`	string	optional	Dataset containing segment rows, optional summary rows, and per-video status rows.

Download the published output schema

View complete JSON

{
  "actorOutputSchemaVersion": 1,
  "description": "SponsorBlock segment rows, per-video/run summaries, and truthful per-video status rows.",
  "properties": {
    "segments": {
      "description": "Dataset containing segment rows, optional summary rows, and per-video status rows.",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "YouTube SponsorBlock Segments Scraper dataset",
      "type": "string"
    }
  },
  "title": "YouTube SponsorBlock Segments Scraper Output"
}

Dataset schema

Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.

Download the published dataset schema

View complete JSON

{
  "actorSpecification": 1,
  "views": {
    "detailed": {
      "display": {
        "component": "table",
        "properties": {
          "actionType": {
            "format": "text",
            "label": "Action"
          },
          "category": {
            "format": "text",
            "label": "Category"
          },
          "categoryName": {
            "format": "text",
            "label": "Category Name"
          },
          "channelName": {
            "format": "text",
            "label": "Channel"
          },
          "durationSeconds": {
            "format": "number",
            "label": "Duration (s)"
          },
          "endTime": {
            "format": "number",
            "label": "End (s)"
          },
          "error": {
            "format": "text",
            "label": "Error"
          },
          "locked": {
            "format": "boolean",
            "label": "Locked"
          },
          "recordType": {
            "format": "text",
            "label": "Type"
          },
          "scrapedAt": {
            "format": "text",
            "label": "Scraped At"
          },
          "segmentId": {
            "format": "text",
            "label": "Segment ID"
          },
          "startTime": {
            "format": "number",
            "label": "Start (s)"
          },
          "status": {
            "format": "text",
            "label": "Status"
          },
          "submitterName": {
            "format": "text",
            "label": "Submitter"
          },
          "thumbnailUrl": {
            "format": "image",
            "label": "Thumbnail"
          },
          "videoDurationSeconds": {
            "format": "number",
            "label": "Video Duration (s)"
          },
          "videoId": {
            "format": "text",
            "label": "Video ID"
          },
          "videoTitle": {
            "format": "text",
            "label": "Video title"
          },
          "videoUrl": {
            "format": "link",
            "label": "Video URL"
          },
          "views": {
            "format": "number",
            "label": "Views"
          },
          "votes": {
            "format": "number",
            "label": "Votes"
          }
        }
      },
      "title": "Detailed",
      "transformation": {
        "fields": [
          "recordType",
          "videoId",
          "videoUrl",
          "segmentId",
          "category",
          "categoryName",
          "actionType",
          "actionName",
          "startTime",
          "endTime",
          "durationSeconds",
          "videoDurationSeconds",
          "votes",
          "locked",
          "views",
          "timeSubmitted",
          "hidden",
          "shadowHidden",
          "submitterId",
          "submitterName",
          "submitterSegmentCount",
          "description",
          "videoTitle",
          "channelName",
          "channelUrl",
          "channelId",
          "thumbnailUrl",
          "youtubeDurationSeconds",
          "videoViewCount",
          "publishedAt",
          "isLive",
          "status",
          "error",
          "scrapedAt"
        ]
      }
    },
    "overview": {
      "display": {
        "component": "table",
        "properties": {
          "actionType": {
            "format": "text",
            "label": "Action"
          },
          "category": {
            "format": "text",
            "label": "Category"
          },
          "durationSeconds": {
            "format": "number",
            "label": "Duration (s)"
          },
          "endTime": {
            "format": "number",
            "label": "End (s)"
          },
          "recordType": {
            "format": "text",
            "label": "Type"
          },
          "startTime": {
            "format": "number",
            "label": "Start (s)"
          },
          "videoId": {
            "format": "text",
            "label": "Video ID"
          },
          "videoTitle": {
            "format": "text",
            "label": "Video title"
          },
          "videoUrl": {
            "format": "link",
            "label": "Video URL"
          },
          "votes": {
            "format": "number",
            "label": "Votes"
          }
        }
      },
      "title": "SponsorBlock segments",
      "transformation": {
        "fields": [
          "recordType",
          "videoId",
          "category",
          "actionType",
          "startTime",
          "endTime",
          "durationSeconds",
          "votes",
          "videoTitle",
          "videoUrl"
        ]
      }
    },
    "summaries": {
      "display": {
        "component": "table",
        "properties": {
          "averageSegmentSeconds": {
            "format": "number",
            "label": "Average seconds"
          },
          "channelName": {
            "format": "text",
            "label": "Channel"
          },
          "longestSegmentSeconds": {
            "format": "number",
            "label": "Longest seconds"
          },
          "recordType": {
            "format": "text",
            "label": "Type"
          },
          "scrapedAt": {
            "format": "text",
            "label": "Scraped At"
          },
          "segmentCount": {
            "format": "number",
            "label": "Segments"
          },
          "source": {
            "format": "text",
            "label": "Source"
          },
          "totalSegmentSeconds": {
            "format": "number",
            "label": "Total seconds"
          },
          "videoDurationSeconds": {
            "format": "number",
            "label": "Video duration (s)"
          },
          "videoId": {
            "format": "text",
            "label": "Video ID"
          },
          "videoTitle": {
            "format": "text",
            "label": "Video title"
          }
        }
      },
      "title": "Summaries",
      "transformation": {
        "fields": [
          "recordType",
          "videoId",
          "videoTitle",
          "channelName",
          "source",
          "segmentCount",
          "totalSegmentSeconds",
          "averageSegmentSeconds",
          "longestSegmentSeconds",
          "videoDurationSeconds",
          "categories",
          "actions",
          "scrapedAt"
        ]
      }
    }
  }
}

Key-value schema

Published key-value store definitions, when provided by this build.

This definition is not present in the default published build. See the published README for available documentation.

Published README

Read the full published documentation

YouTube SponsorBlock Segments Scraper

Export crowdsourced SponsorBlock timestamps for any batch of YouTube videos. Every row is one segment: what it is, when it starts and ends, how the community voted, who submitted it when that is public, and the YouTube title, channel, and thumbnail that make the segment easy to join onto other datasets.

No YouTube login, SponsorBlock account, API key, browser, or proxy is needed. The actor reads the public SponsorBlock database and YouTube's public metadata endpoints.

Two ways to read the data

Visible segments (default) — exactly what SponsorBlock returns to its extension: the segments viewers are currently offered, with the video duration attached to each segment.
All submissions — the full search database, with views and submission time. Hidden, shadow-hidden, and disputed submissions are included only when Include hidden submissions is enabled. This mode is for research and moderation work, not for deciding what to skip.

Both modes accept the same category, action, vote, and per-video cap filters.

What you get

One dataset row per segment. Status rows explain videos with no matching segments, invalid inputs, or a failed lookup. Optional summary rows give per-video and whole-run totals.

Field	Example	Meaning
recordType	`segment`	`segment`, `status`, `videoSummary`, or `runSummary`
videoId	`7wtfhZwyrcc`	11-character YouTube ID
videoUrl	`https://www.youtube.com/watch?v=7wtfhZwyrcc`	Canonical watch URL
segmentId	`1561e818...`	SponsorBlock segment UUID
category / categoryName	`sponsor` / `Sponsor`	Category key and readable label
actionType / actionName	`skip` / `Skip`	Skip, mute, full video, highlight/POI, or chapter
startTime / endTime	`0` / `31.861`	Seconds from the start of the video
durationSeconds	`31.861`	Segment length in seconds
videoDurationSeconds	`361`	Video duration reported by SponsorBlock or YouTube
votes	`0`	Community vote score
locked	`false`	Whether the segment is locked from edits
views	`213`	Reported views on the submission (when available)
timeSubmitted	`2021-06-07T01:55:42+00:00`	Submission time (when available)
hidden / shadowHidden	`false`	Moderation or shadowban state (all-submissions mode)
description	`Pre-Lyrics`	Community note, when one exists
submitterId	`62fc5a8d...`	Public SponsorBlock submitter ID
submitterName	`blabdude`	Public username, when the submitter set one
submitterSegmentCount	`23402`	Public submitter segment count
submitterReputation	`27`	Public submitter reputation score
submitterMinutesSaved	`13669789.992`	Public minutes-saved total
submitterViewCount	`41955231`	Public submitter view total
submitterVip	`true`	Public VIP flag
videoTitle	`Imagine Dragons - Believer...`	YouTube title from oEmbed/player
channelName / channelId	`ImagineDragonsVEVO` / `UCpx_k...`	Channel name and ID
channelUrl	`https://www.youtube.com/@ImagineDragonsVEVO`	Channel URL
thumbnailUrl	`https://i.ytimg.com/...`	Public thumbnail
youtubeDurationSeconds	`217`	Duration reported by YouTube
videoViewCount	`3072396590`	YouTube view count
publishedAt	`2017-03-07`	YouTube publish date
isLive	`false`	Live-stream flag
status	`no_segments`	Status rows only
error	`...`	Status rows only
scrapedAt	`2026-11-05T...`	Capture timestamp

Every empty value is omitted at every depth. There are no null placeholders, empty strings, empty lists, or empty objects in the dataset.

Status rows

status	Meaning
`no_segments`	The lookup succeeded but no segment matched the category, action, vote, hidden, or cap filters.
`invalid_video`	The input was not a YouTube video URL or ID.
`failed`	SponsorBlock did not return a usable response after retries.

Summary rows

Set Include summary rows to add:

videoSummary per processed video: segmentCount, totalSegmentSeconds, averageSegmentSeconds, longestSegmentSeconds, category and action counts, and the YouTube metadata.
runSummary once per run: requested/processed/with-segments/without-segments/failed counts, total segment count and seconds, category and action totals.

Input

Field	Type	Default	Description
`videoUrls`	string array, required	—	YouTube URLs or 11-character IDs. Watch, `youtu.be`, Shorts, live, embed, music, and no-cookie links are accepted. Add as many as you need.
`categories`	multi-select	all	Sponsor, Unpaid/Self Promotion, Interaction Reminder, Intro, Outro, Preview/Recap, Hook, Non-Music Section, Filler Tangent, Highlight, Exclusive Access, Chapter.
`actionTypes`	multi-select	all	Skip, Mute, Full video, Highlight/POI, Chapter.
`source`	select	`visible`	Visible segments or all submissions.
`minVotes`	integer	`0`	`-2` includes every submission, `0` drops downvoted ones, higher values keep only well-confirmed segments.
`includeHiddenSegments`	boolean	`false`	Include hidden/shadow-hidden submissions in all-submissions mode.
`includeDescriptions`	boolean	`true`	Include community notes.
`includeSubmitterInfo`	boolean	`true`	Add public submitter name and stats, cached per submitter.
`includeYouTubeMetadata`	boolean	`true`	Add YouTube title, channel, thumbnail, duration, views, publish date, and live flag.
`includeSummary`	boolean	`false`	Add per-video and run summary rows.
`maxSegmentsPerVideo`	integer	`0`	Keep at most N segments per video after filtering and sorting. `0` means no limit.
`concurrency`	integer	`4`	Videos processed at once, from 1 to 10.

Legacy input keys from older tasks are still honored in code: videoIds, videoIDs, videos, urls, videoId, videoUrl, category, actionType, actions, and includeDescription. A comma- or newline-separated videoUrls string also works. They are intentionally not shown in the input form.

Example: batch with filters

{
  "videoUrls": [
    "https://www.youtube.com/watch?v=9bZkp7q19f0",
    "https://youtu.be/kJQP7kiw5Fk",
    "dQw4w9WgXcQ"
  ],
  "categories": ["sponsor", "selfpromo", "intro", "outro"],
  "actionTypes": ["skip"],
  "minVotes": 0,
  "includeYouTubeMetadata": true,
  "includeSummary": true,
  "maxSegmentsPerVideo": 25,
  "concurrency": 4
}

Example: full research mode

{
  "videoUrls": ["kJQP7kiw5Fk"],
  "source": "all",
  "minVotes": -2,
  "includeHiddenSegments": true,
  "includeSubmitterInfo": true,
  "includeYouTubeMetadata": true
}

Use cases

Player overlays and cut lists — exact start/end times and the recommended action.
Sponsor-load analytics — sponsor seconds as a share of total runtime, by video or channel.
Dataset enrichment — stable segment UUIDs plus video/channel/thumbnail join keys.
Transcript cleanup — remove sponsor, intro, outro, and self-promo spans before analysis.
Community research — compare submissions, votes, lock state, and public submitter stats.

FAQ

What is SponsorBlock?

SponsorBlock is a public crowdsourced database of timestamped YouTube segments such as sponsor reads, intros, outros, and self-promotions.

Do I need cookies, an API key, or a proxy?

No. Every request uses public endpoints. The actor never asks for credentials and never configures a proxy.

Why does one video return no rows?

SponsorBlock is crowdsourced. A video may have no submissions, or every submission may be filtered out by the selected categories, actions, votes, hidden setting, or per-video cap. A no_segments status row tells you which case occurred.

What is the difference between visible segments and all submissions?

Visible segments are what SponsorBlock would currently act on. All submissions also includes hidden, shadow-hidden, and disputed records, which is useful for research but should not be used to build a skip list.

Why do some rows have no thumbnail or title?

Age-restricted, private, or deleted videos can reject the public YouTube metadata endpoints. Segments are still returned; the unavailable metadata fields are simply omitted.

Why is submitterName sometimes missing?

SponsorBlock only exposes a public username when the submitter set one and the public lookup succeeds. Otherwise the row keeps the public submitterId and any aggregate stats that were available.

Why do some segments have zero duration or start and end at zero?

full and some chapter/poi submissions use a single point or the whole video. The actor preserves exactly what SponsorBlock stores and does not invent times.

Can I get the global SponsorBlock leaderboard?

No. The public getTopUsers endpoint is disabled and returns 404. The actor does not expose a mode that cannot return real data.

Does this download videos, captions, or promo codes?

No. It reads timestamps and public metadata only. Promo codes are not part of the SponsorBlock database and are out of scope.

Is this affiliated with YouTube or SponsorBlock?

No. It is an independent reader of public APIs and is not endorsed by either project.

Limits

SponsorBlock coverage is community-driven and varies by video and channel.
Votes, views, hidden state, and lock state are a snapshot at fetch time.
source=all is a separate database view, not a moderation tool; it never submits, votes, or edits anything.
getTopUsers is disabled upstream, and mute submissions may be absent for a given video.
The actor keeps every existing output field and adds new ones; old tasks continue to work.

Python quickstart

Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.

Open the step-by-step Python guide →

Source build DHJ6AF7rUGBo2bUjK. Documentation is regenerated from the default published build; private drafts are not included.