---
title: "Search YouTube videos or channels"
method: GET
path: "/api/v2/youtube/search"
tags: ["YouTube search"]
---

# Search YouTube videos or channels

`GET /api/v2/youtube/search`

Search YouTube for videos or channels.

- `type=video` (default): Returns video results with titles, thumbnails, view counts, etc.
- `type=channel`: Returns channel results with handles, subscriber counts, etc.

Returns YouTube's full page (~20 items) per call.

**Pagination:** The response includes `continuation_token` (when `has_more=true`). To fetch the next page, call the endpoint again with `continuation=<token>` and omit `q`/`type` (the token already encodes them).

**Credit cost:** 1 credit per successful request (each page).

## Query parameters

- `q` string, nullable — Search query (required for first page)
- `type` 'video' | 'channel'
- `continuation` string, nullable — Continuation token from previous page. When provided, q/type are ignored.

## Response `200`

Successful Response

- SearchResponse
  - `results` union[]
    - union
      - VideoResult
        - `type` string
        - `videoId` string, nullable
        - `title` string, nullable
        - `channelId` string, nullable
        - `channelTitle` string, nullable
        - `channelHandle` string, nullable
        - `channelVerified` boolean
        - `lengthText` string, nullable
        - `viewCountText` string, nullable
        - `publishedTimeText` string, nullable
        - `hasCaptions` boolean
        - `thumbnails` Thumbnail[]
          - `url` string, required
          - `width` integer, nullable
          - `height` integer, nullable
      - ChannelResult
        - `type` string
        - `channelId` string, nullable
        - `title` string, nullable
        - `handle` string, nullable
        - `url` string, nullable
        - `description` string, nullable
        - `subscriberCount` string, nullable
        - `verified` boolean
        - `rssUrl` string, nullable
        - `thumbnails` Thumbnail[]
          - `url` string, required
          - `width` integer, nullable
          - `height` integer, nullable
  - `result_count` integer
  - `continuation_token` string, nullable
  - `has_more` boolean

## Other responses

- `400` — **Bad Request** - Invalid parameter combination. Provide either `q` or `continuation`, not both.
- `401` — Unauthorized - invalid Authorization format or API key
- `402` — Payment Required - inactive plan or exhausted credits
- `408` — **Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).
- `422` — **Validation Error** - Invalid input format. **Do not retry** with the same input.
- `429` — **Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.
- `500` — **Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.
- `503` — **Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.

---

[API](https://skmtc.dev/transcriptapi/apis/youtube-transcript-api-public.md) · [All operations](https://skmtc.dev/transcriptapi/apis/youtube-transcript-api-public/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/transcriptapi/youtube-transcript-api-public/revisions/3203c2d6486c/schema)