YouTube Search

Search YouTube without a YouTube Data API key and get back structured video results — video ID, title, thumbnail, channel, duration, view count, and a description snippet — ready to feed into transcript or metadata endpoints.

Method Endpoint Returns
GET /v1/youtube/search {query, results[], nextPageToken}

Base URL: https://youtube.toolkitapi.io

Every request needs an X-API-Key header.

Related pages: YouTube Playlist · YouTube Playlist Videos

Request parameters

Parameter In Type Required Default Description
query query string yes — Search terms, as you'd type them into youtube.com. Missing → 422.
limit query integer no 20 Maximum number of results, 1–50. Out-of-range → 422.

URL-encode the query (curl -G --data-urlencode, params= in Python, URLSearchParams in JS). Multi-word queries become +/%20 separated automatically by those helpers.

Response

{
  "query": "python tutorial",
  "results": [
    {
      "id": "rfscVS0vtbw",
      "type": "video",
      "title": "Learn Python - Full Course for Beginners [Tutorial]",
      "url": "https://www.youtube.com/watch?v=rfscVS0vtbw",
      "thumbnailUrl": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg",
      "description": "This course will give you a full introduction into all of the core concepts in python.",
      "channelName": "freeCodeCamp.org",
      "duration": 16194,
      "viewCount": 45000000
    }
  ],
  "nextPageToken": null
}
Field Type Notes
query string Echo of your query
results array Up to limit items
results[].id string 11-character video ID
results[].type string Currently always "video"
results[].title string Video title
results[].url string Canonical https://www.youtube.com/watch?v=<id>
results[].thumbnailUrl string https://i.ytimg.com/vi/<id>/hqdefault.jpg
results[].description string | null Snippet from the result's metadata, when YouTube provides one
results[].channelName string | null Uploading channel's display name
results[].duration integer | null Duration in seconds
results[].viewCount integer | null View count as displayed (abbreviated values are approximated)
results[].publishedAt string | null Schema field; not currently populated
nextPageToken string | null Schema field; always null today — see pagination below

What is and isn't returned

The service scrapes youtube.com/results and parses the initialData payload, walking only videoRenderer entries. Practical consequences:

  • Videos only. Channels and playlists that YouTube shows in search results are skipped, even though type is typed as video | channel | playlist in the schema.
  • No pagination. To get more than one page, vary limit (max 50) or issue narrower queries.
  • Abbreviated counts. viewCount derives from display text ("1.2M views" → 1200000), so it is approximate for large numbers.
  • Tolerates upstream failures. Scrape or parse errors are logged and return 200 with results: []. An empty list for an obvious query means retry, not "zero results".

Discovery → processing pipeline

Search for candidate videos, take results[].id, then call /v1/youtube/video for full metadata or /v1/youtube/transcript for captions. IDs from search need no further parsing.

Examples

curl

curl -G "https://youtube.toolkitapi.io/v1/youtube/search" \
  --data-urlencode "query=python tutorial" \
  --data-urlencode "limit=5" \
  -H "X-API-Key: $YOUTUBE_API_KEY"

Python

import httpx

API = "https://youtube.toolkitapi.io"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}


def search_videos(query: str, limit: int = 10) -> list[dict]:
    resp = httpx.get(
        f"{API}/v1/youtube/search",
        params={"query": query, "limit": limit},
        headers=HEADERS,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["results"]


for hit in search_videos("fastapi tutorial", limit=5):
    mins = (hit["duration"] or 0) // 60
    print(f'{hit["id"]}  {mins:>3}m  {hit["title"][:60]}')

JavaScript

const API = "https://youtube.toolkitapi.io";
const HEADERS = { "X-API-Key": "YOUR_API_KEY" };

async function searchVideos(query, limit = 10) {
  const qs = new URLSearchParams({ query, limit: String(limit) });
  const res = await fetch(`${API}/v1/youtube/search?${qs}`, { headers: HEADERS });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  return (await res.json()).results;
}

const hits = await searchVideos("fastapi tutorial", 5);
hits.forEach((h) => console.log(h.id, h.title, h.channelName));

Errors

Status When
401 Missing or invalid X-API-Key
422 query missing, or limit outside 1–50
429 Rate limit exceeded
5xx Upstream failure

A 200 with an empty results array is also possible on scrape failure — retry with backoff before treating it as "no matches".