Search YouTube or a channel

Find videos before fetching their transcripts. Both search endpoints require an API key, cost zero credits, and count toward your request limit. Results are YouTube's rankings, not an exhaustive exact-match filter.

Search YouTube

GET/api/v1/search

Name	Type	Description
`q`required	`string`	Search terms, 1 to 200 characters. Required on every request, including continuation pages.
`type`	`string`	all (default), video, channel, or playlist. The all mode can also return Shorts.
`sort_by`	`string`	relevance (default), date, views, or rating.
`upload_date`	`string`	hour, today, week, month, or year. For video searches.
`duration`	`string`	short (under 4 minutes), medium (4 to 20 minutes), or long (over 20 minutes). For video searches.
`continuation`	`string`	Opaque token from the previous response. Omit to start a new search.

bash

curl --get -H "Authorization: Bearer yvt_live_..." \
  --data-urlencode "q=electric car review" \
  --data-urlencode "type=video" \
  --data-urlencode "sort_by=date" \
  --data-urlencode "upload_date=month" \
  "https://api.youtubevideotranscript.io/api/v1/search"

Response

Illustrative response with one video row. Page sizes vary; video searches commonly return about 20 results.

json

{
  "query": "electric car review",
  "estimated_results": null,
  "results": [{
    "result_type": "video",
    "video_id": "abc12345678",
    "title": "Electric car review",
    "url": "https://www.youtube.com/watch?v=abc12345678",
    "thumbnail": "https://i.ytimg.com/vi/abc12345678/hqdefault.jpg",
    "duration_seconds": 840,
    "published": "2 weeks ago",
    "views": "120K views",
    "is_live": false,
    "channel_name": "Example channel",
    "channel_id": "UC...",
    "description": "Our experience after a month of driving."
  }],
  "continuation": "OPAQUE_TOKEN"
}

estimated_results is YouTube's estimate as a string, or null when absent. It is not an exact total.

Result types

Branch on result_type. Every row has title,url, and a nullable thumbnail. Fields for other result types are omitted, not filled with nulls.

Name	Type	Description
`video`	`result_type`	video_id; nullable duration_seconds, published, views, channel_name, channel_id, and description; boolean is_live.
`channel`	`result_type`	channel_id; nullable handle, subscribers, and description.
`playlist`	`result_type`	playlist_id; nullable video_count and channel_name. video_count is display text, not a number.
`shorts`	`result_type`	video_id and nullable views. No duration_seconds or channel fields.

Views, subscribers, and publication dates in search rows are display text: sometimes rounded or relative, sometimes a full count as text. Use video info for numeric video views and an optional publish timestamp.

Search inside a channel

GET/api/v1/channel/search

Name	Type	Description
`url`	`string`	Required on the first page: a channel URL, @handle, or UC... channel ID. May be omitted with a continuation.
`q`required	`string`	Search terms, 1 to 200 characters. Required on every page.
`continuation`	`string`	Token from the previous channel-search response.

bash

curl --get -H "Authorization: Bearer yvt_live_..." \
  --data-urlencode "url=@mkbhd" \
  --data-urlencode "q=iphone review" \
  "https://api.youtubevideotranscript.io/api/v1/channel/search"

Returns channel_id, query, results, and continuation. Rows use the video shape above, commonly about 30 per page. There is no estimated_results field or sort/date/duration filter on this endpoint. Short videos can appear.

Continue a search

bash

curl --get -H "Authorization: Bearer yvt_live_..." \
  --data-urlencode "q=electric car review" \
  --data-urlencode "continuation=OPAQUE_TOKEN" \
  "https://api.youtubevideotranscript.io/api/v1/search"

Continue until continuation is null. Tokens retain the original query and filters, and channel-search tokens retain the channel too. Keep sending the original q to satisfy request validation; changing it alongside a token does not start a new search. To change the query, channel, or filters, omit the token.

Errors

Missing or oversized queries, invalid enum values, invalid tokens, and non-channel inputs to channel search return 400 bad_request. No matches is a successful response with an empty results array. Authentication, rate-limit, and upstream errors follow the standard error contract.