---
name: search-youtube
description: Search YouTube for videos or channels via the YouTubeTranscriptAPI search endpoint. Use whenever the user wants to find YouTube content by query.
---

# Search YouTube

Search YouTube for videos or channels with rich metadata.

## Endpoint

`GET https://youtubetranscriptapi.com/api/v2/youtube/search`

## Authentication

Bearer token in `Authorization` header. Set `YT_API_KEY` environment variable.

```bash
curl -X GET "https://youtubetranscriptapi.com/api/v2/youtube/search?q=python+tutorial&limit=10" \
  -H "Authorization: Bearer $YT_API_KEY"
```

## Parameters

- `q` (required) — Search query, 1–200 characters
- `type` (default `video`) — `video` or `channel`
- `limit` (default 20, max 50)

## Response shape

```json
{
  "results": [
    {
      "type": "video",
      "videoId": "dQw4w9WgXcQ",
      "title": "...",
      "channelId": "UC...",
      "channelTitle": "...",
      "channelHandle": "@handle",
      "lengthText": "3:33",
      "viewCountText": "1.5B views",
      "publishedTimeText": "14 years ago",
      "hasCaptions": true,
      "thumbnails": [{ "url": "...", "width": 120, "height": 90 }]
    }
  ],
  "result_count": 20
}
```

## Cost

4 credits per call (whether or not results are found, as long as HTTP 200).

## Workflow tip

Common pattern: search → pick a result → fetch its transcript. Use the `videoId` from search results as `video_url` in the transcript endpoint.

## Reference

Full docs: https://youtubetranscriptapi.com/docs/api/search