youtube

youtube

The deterministic read path for public YouTube data through UnifAPI. This is a Data Skill: it does not run a marketing job on its own — it names the concrete youtube/... operations, response shapes, and the real coverage limits so any channel- or content-first workflow (creator vetting, competitor reception, content demand) reads from one known recipe instead of rediscovering the surface each time.

Read-only — eyes, not hands. It researches public YouTube data and returns cited records; it never uploads, comments, or subscribes, and UnifAPI never holds YouTube credentials.

Use the unifapi skill for live evidence

Connect once through the shared unifapi skill (OAuth MCP), then call the operations below. Channels are keyed by {channel_id} and videos by {video_id} — resolve a handle or URL to a channel id first (see Gotchas). Keep any billing metadata so the output can state record cost.

Response contract

Single-entity endpoints return the object in data:

{
  "request_id": "unif_...",
  "data": {},
  "billing": { "records_charged": 1, "balance_remaining": 99 }
}

List endpoints return an array in data plus pagination:

{
  "request_id": "unif_...",
  "data": [],
  "pagination": { "has_more": false, "next_cursor": null },
  "billing": { "records_charged": 1 }
}

When pagination.has_more is true, pass pagination.next_cursor as the next request's cursor. Always preserve billing when reporting cost.

Core operations

Need	Operation
Search videos	youtube/search (?q=..., optional sort_by/upload_date/duration/region/language)
Search channels / playlists	youtube/search/channels · youtube/search/playlists (?q=...)
Trending	youtube/trending (optional type = now/music/gaming/movies)
Hashtag videos	youtube/hashtags/{tag}/videos
Resolve handle/URL → id	youtube/resolve/channel-id (?url=...)
Channel page	youtube/channels/{channel_id}
Channel videos / shorts	youtube/channels/{channel_id}/videos · .../shorts
Channel playlists	youtube/channels/{channel_id}/playlists
Channel community posts	youtube/channels/{channel_id}/community
Search within a channel	youtube/channels/{channel_id}/search (?q=...)
Video metadata	youtube/videos/{video_id}
Related videos	youtube/videos/{video_id}/related
Video comments	youtube/videos/{video_id}/comments (optional sort_by = top/newest)
Video captions / transcript	youtube/videos/{video_id}/captions
Playlist page / videos	youtube/playlists/{playlist_id} · .../videos

Need a field not listed here? Use the unifapi skill's get_operation to read the exact schema before calling — but pick the operation from this table, don't discover blind.

Workflow

The deterministic recipes. Pick the one that matches the job; each names exactly what to call.

1. Frame the query. Call youtube/search?q=... for who owns a topic, or youtube/trending for what's surging now.
2. Resolve a channel. Call youtube/resolve/channel-id?url=... to get the channel_id, then youtube/channels/{channel_id} for subscriber_count, video_count, and view_count.
3. Read a channel's output. Call youtube/channels/{channel_id}/videos (and .../shorts); each video's view_count is the demand signal. Page via next_cursor. youtube/channels/{channel_id}/playlists maps how the catalog is organized; youtube/channels/{channel_id}/community reads announcements and engagement outside videos; youtube/channels/{channel_id}/search?q=... finds a creator's coverage of one topic without scanning the whole catalog.
4. Read a video and its neighborhood. Call youtube/videos/{video_id} for metadata (now including like_count, category, published_at, has_captions), then youtube/videos/{video_id}/related to map adjacent demand and competing content.
5. Read audience and transcript. Call youtube/videos/{video_id}/comments (sort_by top/newest) for what the audience says — raw comment text, like and reply counts; any sentiment or FAQ grouping is yours to compute, the API returns text only. Call youtube/videos/{video_id}/captions for caption tracks (timed-text url per language) to read or analyze the transcript.
6. Walk a playlist or hashtag. Call youtube/playlists/{playlist_id} then .../videos to ingest a curated series in order; youtube/hashtags/{tag}/videos tracks a campaign or trend across creators.
7. Size topic demand. Aggregate view_count across the search and related results for a topic; title, description, and keywords show how the topic is framed.
8. Cite everything. Every figure ties back to the video or channel it came from; report billing.records_charged (or estimate when billing metadata is absent).

Shape notes

• YouTubeChannel — keyed by {channel_id}. subscriber_count, video_count, view_count, handle, keywords, links, country, created_at. is_verified is not populated by the upstream and is always false — don't report verification you can't read.
• YouTubeVideo — keyed by {video_id}. view_count, like_count (best-effort; 0 when the creator hides it), category, channel_id, author, duration_seconds, keywords, published_at, has_captions, is_live, is_private.
• YouTubeVideoPreview — search/related/list rows: adds published_time. category is part of the shape but empty on list rows (only YouTubeVideo detail carries it).
• YouTubeComment — text, author, author_channel_id, like_count, reply_count, published_time, is_verified, is_creator. Text only — no sentiment field.
• YouTubeCaptions — video_id, tracks[] (language_code, timed-text url, is_translatable), translation_languages[]. Single object, billed as one record. Track urls are time-limited.
• YouTubePlaylist / YouTubePlaylistPreview — playlist title, channel_id, author, video_count (detail adds view_count, last_updated; preview adds first_video_id).
• YouTubeChannelPreview — search-channels rows: title, handle, description, subscriber_count, video_count.
• YouTubeCommunityPost — text, author, vote_count, reply_count, attachment_type, image_url.

Gotchas

• Resolve only goes to channel ids. youtube/resolve/channel-id?url=... resolves a handle or URL to a {channel_id} — call it before any youtube/channels/{channel_id}/... call. There is no video- or playlist-id resolver; pass a known {video_id} / {playlist_id} (parse it from the URL yourself).
• Comments are raw text. youtube/videos/{video_id}/comments returns comment text plus like/reply counts — no sentiment, no FAQ grouping. Compute those yourself from the text; don't claim a sentiment field the API doesn't return.
• like_count is best-effort. YouTubeVideo.like_count is 0 when the creator hides likes — treat 0 as "hidden or none," not authoritative.
• is_verified is always false for channels (upstream doesn't expose it) — don't report channel verification.
• Captions can be empty. A video with captions disabled returns tracks: []; check before promising a transcript. Track urls are time-limited.
• Hashtags take the tag with or without a leading # (youtube/hashtags/lofi/videos).
• A low balance can silently truncate list pages: check billing.truncated_due_to_balance — when true the page is partial.

Output

Return the records the calling workflow needs, each cited to its video or channel, plus a one-line cost note (records_charged). When this skill is used directly, a compact demand brief is the default:

**{Channel}** — {subscribers} subscribers, {videos} videos, {totalViews} views. Top videos for {topic}: {title} ({views} views). Related/competitors: {channels}. Evidence: {URLs}. Records: ~{N}.

Related skills

• kol-pricing, creator-shortlist, audience-fit-check (Influencer Marketing) — price and vet YouTube channels on top of this read path.
• competitor-profiling (Competitive Intelligence), content-opportunity-brief (Content Strategy) — reception and content-demand work that reads YouTube first.
• unifapi — the shared data skill: connect MCP and look up exact schemas with get_operation.