CaptapiCaptapi
YouTube · Guide

How to run a YouTube search

TL;DR
To run a YouTube search, sign up for a free Captapi key, then send one GET request to /v1/youtube/search with your input. You get clean JSON back in seconds for 2 credits per call — no OAuth, scraping or platform SDKs. YouTube search with cursor pagination — typed hits, ids, canonical URLs, filters (2 credits/page).
Get your free API keyAPI reference

How to run a YouTube search (step by step)

  1. 1

    Get a free API key

    Create a free Captapi account (100 credits, no card) and generate an API key from the dashboard.

  2. 2

    Call the YouTube Search API

    Send an authenticated GET request to /v1/youtube/search with your input. No OAuth, no scraping setup.

  3. 3

    Read the JSON response

    Parse the clean JSON response. Pass cache=true for a free 24h cache hit; default is always fresh.

Code example

curl "https://api.captapi.com/v1/youtube/search?q=space" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

What the response looks like

{
  "success": true,
  "data": {
    "query": "space",
    "totalReturned": 5,
    "nextCursor": "EtACEgVzcGFjZRrGAlNCU0NBUXRxUm14WGQyaFFVbUpRZDRJQkMwdzVUazFTUzFsVE5uYzBnZ0VMUVhVeWJEWk9iMlo0TUVXQ0FRc3pXamh1TkRONWNDMXRaNElCQzJseU9HcE5lVXhDVXpacmdnRUxaeTFuYTJOM1dXdGtSRUdDQVF0R1RsSTNZVGhxYjBOSGM0SUJDMkpvTVd4amJqSlRVRTVuZ2dFTFZVdHJMV2hWUVd0UGQydUNBUXRvWjAxcVlqVjJhbWhtYTRJQkN6SlVhbnBKTXpWSk5sTmpnZ0VMV2xWMVVVMUtOVTh6V0UyQ0FRdFliWGxrTjBWRFZHeEpXWUlCQzFWek1sb3RWME01Y21GdmdnRUxaVmRmYlc5V05uWnZkRUdDQVF0WloyTlVkMlY1Vmt0a2I3SUJCZ29FQ0JZUUF1b0JCQWdDRUJrJTNEGIHg6BgiC3NlYXJjaC1mZWVk",
    "hasMore": true,
    "results": [
      {
        "type": "video",
        "id": "jFlWwhPRbPw",
        "url": "https://www.youtube.com/watch?v=jFlWwhPRbPw",
        "title": "James Webb Found a Structure So Big It Breaks Known Physics",
        "publishedAt": "2026-07-23T19:42:10.000Z",
        "viewCount": 38769,
        "durationSeconds": 7924,
        "thumbnailUrl": "https://i.ytimg.com/vi/jFlWwhPRbPw/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLA7UvQbAJ_-ucLxF_Y5rLx6Et8OqQ",
        "channelName": "Late Science",
        "channelId": "UCIqH5kGFOM_lP9x_AmPodjQ",
        "channel": {
          "id": "UCIqH5kGFOM_lP9x_AmPodjQ",
          "title": "Late Science",
          "handle": "@Late_Science",
          "url": "https://www.youtube.com/@Late_Science",
          "thumbnail": null
        },
        "badges": [
          "4K"
        ],
        "publishedTimeText": "10 days ago"
      },
      {
        "type": "video",
        "id": "L9NMRKYS6w4",
        "url": "https://www.youtube.com/watch?v=L9NMRKYS6w4",
        "title": "James Webb Detected a Sign of a Different Universe That Shattered Every Model Built Since Einstein",
        "publishedAt": "2026-06-03T19:42:10.000Z",
        "viewCount": 151088,
        "durationSeconds": 6441,
        "thumbnailUrl": "https://i.ytimg.com/vi/L9NMRKYS6w4/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLDucFGeHFH4XAYqCTdLsGr5dul9IA",
        "channelName": "SPACE BEFOREAFTER",
        "channelId": "UCxbnsftoQou1IfWZlEb_1iA",
        "channel": {
          "id": "UCxbnsftoQou1IfWZlEb_1iA",
          "title": "SPACE BEFOREAFTER",
          "handle": "@space-before-after",
          "url": "https://www.youtube.com/@space-before-after",
          "thumbnail": null
        },
        "badges": [],
        "publishedTimeText": "2 months ago"
      }
    ],
    "videos": [
      {
        "type": "video",
        "id": "jFlWwhPRbPw",
        "url": "https://www.youtube.com/watch?v=jFlWwhPRbPw",
        "title": "James Webb Found a Structure So Big It Breaks Known Physics",
        "publishedAt": "2026-07-23T19:42:10.000Z",
        "viewCount": 38769,
        "durationSeconds": 7924,
        "thumbnailUrl": "https://i.ytimg.com/vi/jFlWwhPRbPw/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLA7UvQbAJ_-ucLxF_Y5rLx6Et8OqQ",
        "channelName": "Late Science",
        "channelId": "UCIqH5kGFOM_lP9x_AmPodjQ",
        "channel": {
          "id": "UCIqH5kGFOM_lP9x_AmPodjQ",
          "title": "Late Science",
          "handle": "@Late_Science",
          "url": "https://www.youtube.com/@Late_Science",
          "thumbnail": null
        },
        "badges": [
          "4K"
        ],
        "publishedTimeText": "10 days ago"
      },
      {
        "type": "video",
        "id": "L9NMRKYS6w4",
        "url": "https://www.youtube.com/watch?v=L9NMRKYS6w4",
        "title": "James Webb Detected a Sign of a Different Universe That Shattered Every Model Built Since Einstein",
        "publishedAt": "2026-06-03T19:42:10.000Z",
        "viewCount": 151088,
        "durationSeconds": 6441,
        "thumbnailUrl": "https://i.ytimg.com/vi/L9NMRKYS6w4/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLDucFGeHFH4XAYqCTdLsGr5dul9IA",
        "channelName": "SPACE BEFOREAFTER",
        "channelId": "UCxbnsftoQou1IfWZlEb_1iA",
        "channel": {
          "id": "UCxbnsftoQou1IfWZlEb_1iA",
          "title": "SPACE BEFOREAFTER",
          "handle": "@space-before-after",
          "url": "https://www.youtube.com/@space-before-after",
          "thumbnail": null
        },
        "badges": [],
        "publishedTimeText": "2 months ago"
      }
    ],
    "shorts": [],
    "channels": [],
    "playlists": []
  }
}

Billing metadata (credits charged, cache hit/miss) is returned in the X-Captapi-Credits and X-Captapi-Cache response headers.

Request parameters

NameTypeRequiredDescription
qstring YesSearch query or keywords (min 2 characters).
limitintegerNoMax items to return (default 20, max 200). Flat 2 credits per call.
cursorstringNoPagination cursor. Leave empty for the first page; then pass the nextCursor value returned in the previous response.
typestringNoall | videos | shorts | channels | playlists.
sortBystringNorelevance | date | views | rating (alias: popular→views).
uploadDatestringNoany | today | this_week | this_month | this_year.
durationstringNoany | under_4 | 4_20 | over_20. Applies to long-form videos (not Shorts).
regionstringNoISO country code for localized results (default US).
cachebooleanNoSet true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh.

Frequently asked questions

What does the YouTube Search API do?

The YouTube Search API lets you search and return matching results from a public YouTube query using one GET request to /v1/youtube/search. It returns clean JSON — no OAuth or infrastructure setup required.

How many credits does the YouTube Search API cost?

Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.

Do I need a YouTube API key or OAuth?

No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle proxies, rate limits, retries, and authentication for you.

Is the YouTube Search API suitable for production use?

Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.

Ready to run a YouTube search?

Start free with 100 credits — no credit card required.

Get your free API key