---
title: "Search YouTube"
method: GET
path: "/youtube/search"
tags: ["YouTube"]
---

# Search YouTube

`GET /youtube/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/youtube/search`
- Auth: API key in header `x-api-key`

Returns normalized YouTube search results using YouTube's InnerTube search API.
Pass `continuation_token` from a previous response to retrieve the next page.
Use `q` as the primary query parameter; `search_query` is accepted as an alias.
`hl` and `gl` localize ranking and result context; they default to `en` and `US`.
Named filters cover the public web search filters. Account-only chips such as Watched and Unwatched are not exposed.

## Query parameters

- `q` string
- `search_query` string
- `continuation_token` string
- `type` 'video' | 'shorts' | 'channel' | 'playlist' | 'movie'
- `sort_by` 'relevance' | 'upload_date' | 'view_count' | 'popularity' | 'rating'
- `upload_date` 'last_hour' | 'today' | 'this_week' | 'this_month' | 'this_year'
- `duration` 'under_3_minutes' | 'three_to_20_minutes' | 'over_20_minutes' | 'under_3' | 'three_to_20' | 'over_20' | 'short' | 'medium' | 'long'
- `features` string
- `hl` string
- `gl` string
- `params` string

## Headers

- `x-api-key` string, required

## Response `200`

OK

- YoutubeSearchResponseDoc
  - `code` integer
  - `data` YoutubeSearchResponse
    - `continuation_token` string: Token to pass in the next request to get the following page. Omitted on the last page.
    - `estimated_results` integer: Approximate number of results YouTube reports for the search.
    - `items` YoutubeSearchItem[]: Videos, channels and playlists on this page of results.
      - `badges` string[]: Badge labels shown on the video, such as `HD` or `CC`.
      - `channel_id` string: YouTube channel ID, starting with `UC`.
      - `channel_thumbnail` string: URL of the publishing channel's avatar image.
      - `channel_title` string: Name of the channel that published the video or playlist.
      - `description_snippet` string: Short excerpt of the video or channel description shown in the results.
      - `duration` string: Video length as YouTube displays it, such as `12:34`.
      - `duration_seconds` integer: Video length in seconds.
      - `handle` string: Channel handle, starting with `@`. Set for channel results.
      - `is_live` boolean: Whether the video is a live stream.
      - `is_short` boolean: Whether the video is a YouTube Short.
      - `is_verified` boolean: Whether the channel carries a verified badge.
      - `playlist_id` string: YouTube playlist ID. Set for playlist results.
      - `position` integer: Position of the item on this page of results, starting at 1.
      - `published_text` string: Upload time as YouTube displays it, such as `2 days ago`.
      - `short_view_count` string: Abbreviated view count as YouTube displays it, such as `123K views`.
      - `subscriber_count` string: Subscriber count as YouTube displays it, such as `1.93M subscribers`.
      - `thumbnail` string: URL of the item's thumbnail image.
      - `title` string: Video or playlist title, or channel name.
      - `type` string: Kind of result: `video`, `channel` or `playlist`.
      - `url` string: Link to the video, channel or playlist on YouTube.
      - `video_count` string: Number of videos as YouTube displays it, such as `12 videos`. Set for channel and playlist results.
      - `video_id` string: YouTube video ID. Set for video results.
      - `view_count` string: View count as YouTube displays it, such as `123,456 views`.
    - `query` string: Search text that was run.
  - `msg` string

## Other responses

- `400`: Missing or invalid parameters
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)