YouTube

Two endpoints for YouTube: search to see which videos already win on a topic, and transcript to read what the winner says without watching it. Together they turn an hour of video research into one API call and a summary.

POST/v1/youtube/search

Search

Videos for a query with the numbers that matter: views, likes, comments, duration, channel and publish date.

Costs 0.6 credits per call.

Required attributes

Name
query
Type
string
Description
Search query.

Optional attributes

Name
limit
Type
integer
Description
Videos to return, 5 to 50. Default 10. Capped by your plan.
Name
order
Type
string
Description
relevance, date or viewCount. Default relevance.
Name
country
Type
string
Description
ISO 3166-1 alpha-2 code such as US, ES or MX. Default US. See Countries and languages.

Response fields

Name
videos[].duration_seconds
Type
integer
Description
Length of the video. Under 60 is a Short.
Name
videos[].thumbnail_url
Type
string
Description
High resolution thumbnail, stable and downloadable.

Request

POST

/v1/youtube/search

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/youtube/search \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "protein powder review", "limit": 5, "order": "viewCount"}'

Response

{
  "data": {
    "query": "protein powder review",
    "country": "US",
    "order": "viewcount",
    "count": 5,
    "videos": [
      {
        "video_id": "o01GVtJJ5lA",
        "url": "https://www.youtube.com/watch?v=o01GVtJJ5lA",
        "title": "Worst Pre-Workout Ever? (Don't Use This)",
        "channel": "Sean Nalewanyj Shorts",
        "published_at": "2022-01-02T16:25:41Z",
        "duration_seconds": 60,
        "views": 18613406,
        "likes": 855006,
        "comments": 8604,
        "thumbnail_url": "https://i.ytimg.com/vi/o01GVtJJ5lA/hqdefault.jpg",
        "description": "This might be one of the worst pre-workout supplement combinations in history. Sometimes I wonder if I come of..."
      },
      {
        "video_id": "j_ku8ZEJIrw",
        "url": "https://www.youtube.com/watch?v=j_ku8ZEJIrw",
        "title": "Protein overnight oats 🍫🤤",
        "channel": "Noel Deyzel",
        "published_at": "2022-07-27T17:14:02Z",
        "duration_seconds": 15,
        "views": 12769339,
        "likes": 516346,
        "comments": 2847,
        "thumbnail_url": "https://i.ytimg.com/vi/j_ku8ZEJIrw/hqdefault.jpg",
        "description": "RYSE Supplements (Code \"NOEL\" to save 15% off and support me) • Ryse X Noel Deyzel, Mega dosed Pre-Workout: GO..."
      },
      // ...
    ]
  },
  "meta": {
    "credits_charged": 0.5,
    "credits_remaining": 483.5,
    "request_id": "237fcc3e-0a3f-4719-8214-ca96eac7c9e0"
  }
}

POST/v1/youtube/transcript

Transcript

The transcript of a video with timestamps, from its captions (manual or automatic). Accepts a video id, a watch URL, a youtu.be link or a Shorts URL.

Costs 1.8 credits per call, and nothing at all when the video has captions we can read directly, which is most of them.

Required attributes

Name
video
Type
string
Description
YouTube video id or URL.

Optional attributes

Name
language
Type
string
Description
Preferred caption language, ISO 639-1. Falls back to whatever the video has.

Response fields

Name
segments[].start
Type
number
Description
Seconds from the start of the video.
Name
segments[].text
Type
string
Description
The caption text for that segment.

Returns 404 not_found when the video has no captions of any kind. Refunded.

Request

POST

/v1/youtube/transcript

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/youtube/transcript \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video": "https://youtube.com/shorts/o01GVtJJ5lA"}'

Response

{
  "data": {
    "video_id": "o01GVtJJ5lA",
    "url": "https://www.youtube.com/watch?v=o01GVtJJ5lA",
    "language": "English (a",
    "word_count": 241,
    "transcript": "king here's my current pre-workout stack i started off with one scoop of six star pre-workout it's not the best but it does the job six star is literally one of the absolute worst pre-workouts on the entire market every ...",
    "segments": [
      {
        "start": 0.08,
        "duration": 3.6799999999999997,
        "text": "king here's my current pre-workout stack"
      },
      {
        "start": 2,
        "duration": 3.279,
        "text": "i started off with one scoop of six star"
      },
      // ...
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 94.5,
    "metered": true,
    "request_id": "93d2a3e5-d747-4f69-8b4d-dfa217d4833a"
  }
}

POST/v1/youtube/channel

Channel

A channel's audience and catalogue in one call: subscribers, total views, how many videos it has published and how often, plus its recent videos with views, likes, comments and duration.

Costs 0.6 credits per call. Accepts a handle, a channel id or a channel URL.

Required attributes

Name
channel
Type
string
Description
@mkbhd, UCBJycsmduvYEL83R_U4JriQ, or any channel URL, including the legacy /c/name and /user/name shapes.

Optional attributes

Name
videos
Type
integer
Description
Videos to return, 5 to 50. Default 10. Capped by your plan.
Name
order
Type
string
Description
date or views. Default date. Either way the videos are picked from the channel's 50 most recent uploads, so views ranks recent performance rather than all-time hits.

Response fields

Name
channel.subscribers
Type
integer
Description
null when the channel hides its subscriber count, which is not the same as zero. channel.subscribers_hidden says which case you are in.
Name
stats.uploads_per_month
Type
number
Description
Measured across the window actually read, not over the channel's lifetime. A channel that posted weekly for a year and then stopped does not get reported as weekly.
Name
stats.avg_views
Type
integer
Description
Average across the recent window, which is the number to compare against a single video to see whether it over or under performed.
Name
recent_window
Type
integer
Description
How many uploads the averages were computed from.

Request

POST

/v1/youtube/channel

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/youtube/channel       -H "Authorization: Bearer $PENGU_API_KEY"       -H "Content-Type: application/json"       -d '{"channel": "@mkbhd", "videos": 10, "order": "views"}'

Response

{
  "data": {
    "channel": {
      "id": "UCBJycsmduvYEL83R_U4JriQ",
      "url": "https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ",
      "title": "Marques Brownlee",
      "handle": "mkbhd",
      "country": "US",
      "created_at": "2008-03-21T15:24:50Z",
      "subscribers": 20100000,
      "subscribers_hidden": false,
      "total_views": 4512000000,
      "video_count": 1684
    },
    "checked_at": "2026-10-08T09:14:02.551Z",
    "order": "views",
    "count": 10,
    "recent_window": 50,
    "stats": {
      "avg_views": 1840000,
      "avg_likes": 68400,
      "avg_comments": 4120,
      "uploads_per_month": 6.4
    },
    "videos": [
      {
        "video_id": "dQw4w9WgXcQ",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "title": "The best phone of the year",
        "published_at": "2026-09-28T14:00:11Z",
        "duration_seconds": 964,
        "views": 4120000,
        "likes": 152000,
        "comments": 9840,
        "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"
      }
    ]
  },
  "meta": {
    "credits_charged": 0.5,
    "credits_remaining": 2799.5,
    "request_id": "7b2e4a19-0c63-4f85-9d21-6a3f1c58e204"
  }
}