Docs · Search YouTube

Search YouTube

Search YouTube by keyword for videos, Shorts, channels and playlists, with date, length and type filters.

1 credit per callFresh within 15 minutesMCP tool: youtube_search

GEThttps://api.lurkapi.com/v1/youtube/search

When to use this

Use it for trend, topic and competitor research: what YouTube's search page shows for a keyword, split into videos, shorts, channels, playlists and lives (streaming now). About 20 results per page. Narrow it with type, uploadDate, duration (videos only) and sortBy=popular.

Video results carry views as YouTube shows them, a description snippet and the channel. Counts may be rounded; video details returns exact views. Shorts carry title and views only; pass a Short's url to the video endpoint for the rest.

Pagination. Pass the response's continuationToken back as continuationToken (with the same query) for the next page; it's null on the last page.

Example request

Copy one and replace YOUR_API_KEY with your API key (get one free). The code versions read the key from the LURKAPI_API_KEY environment variable instead.

curl "https://api.lurkapi.com/v1/youtube/search?query=running+shoes" \
  -H "x-api-key: YOUR_API_KEY"

Paste it into a terminal, with your key in place of YOUR_API_KEY.

const params = new URLSearchParams({
  query: "running shoes",
});
const res = await fetch(`https://api.lurkapi.com/v1/youtube/search?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_API_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.videos);

Node 18+. Save it as lurk.mjs and run node lurk.mjs. It reads your key from LURKAPI_API_KEY.

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/youtube/search",
    params={
        "query": "running shoes",
    },
    headers={"x-api-key": os.environ["LURKAPI_API_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["videos"])

Run pip install requests, save it as lurk.py and run python lurk.py. It reads your key from LURKAPI_API_KEY.

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"time"
)

func main() {
	params := url.Values{}
	params.Set("query", "running shoes")
	req, _ := http.NewRequest("GET", "https://api.lurkapi.com/v1/youtube/search?"+params.Encode(), nil)
	req.Header.Set("x-api-key", os.Getenv("LURKAPI_API_KEY"))

	client := &http.Client{Timeout: 60 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if data["success"] != true {
		panic(fmt.Sprintf("%v: %v", data["code"], data["error"]))
	}
	out, _ := json.MarshalIndent(data["videos"], "", "  ")
	fmt.Println(string(out))
}

Save it as main.go and run go run main.go. It reads your key from LURKAPI_API_KEY.

<?php
$params = http_build_query([
    'query' => 'running shoes',
]);
$context = stream_context_create(['http' => [
    'header' => 'x-api-key: ' . getenv('LURKAPI_API_KEY'),
    'timeout' => 60,
    'ignore_errors' => true,
]]);
$body = file_get_contents('https://api.lurkapi.com/v1/youtube/search?' . $params, false, $context);
$data = json_decode($body, true);
if (!$data['success']) {
    throw new Exception("{$data['code']}: {$data['error']}");
}
print_r($data['videos']);

Save it as lurk.php and run php lurk.php. It reads your key from LURKAPI_API_KEY.

require 'json'
require 'net/http'

uri = URI('https://api.lurkapi.com/v1/youtube/search')
uri.query = URI.encode_www_form(
  'query' => 'running shoes',
)
req = Net::HTTP::Get.new(uri)
req['x-api-key'] = ENV.fetch('LURKAPI_API_KEY')
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 60) do |http|
  http.request(req)
end
data = JSON.parse(res.body)
raise "#{data['code']}: #{data['error']}" unless data['success']
puts JSON.pretty_generate(data['videos'])

Save it as lurk.rb and run ruby lurk.rb. It reads your key from LURKAPI_API_KEY.

Parameters

Add them to the URL after a ?, as in ?query=running+shoes. Join several with &.

Parameter	Description
`query` stringrequired	Keywords, e.g. `running shoes`. YouTube's operators work, e.g. `intitle:"air max"`. Example `running shoes`
`type` stringoptional	What to search for. `all` mixes them like youtube.com. One of `allvideosshortschannelsplaylists` Default `all`
`uploadDate` stringoptional	Only results uploaded in this window. One of `anytodaythis_weekthis_monththis_year` Default `any`
`duration` stringoptional	Video length. Doesn't apply to Shorts. One of `anyunder_3_minbetween_3_and_20_minover_20_min` Default `any`
`sortBy` stringoptional	`relevance` (YouTube's default) or `popular` (most viewed first). One of `relevancepopular` Default `relevance`
`continuationToken` stringoptional	The `continuationToken` from the previous response, for the next page.

Example response

A real response, captured from the live API. Lists are trimmed to a couple of items, and long text such as media links is cut short with ….

Show the example response (3 KB)

{
  "success": true,
  "credits_remaining": 999992,
  "credits_charged": 1,
  "videos": [
    {
      "type": "video",
      "id": "z5mWgBMOFJk",
      "url": "https://www.youtube.com/watch?v=z5mWgBMOFJk",
      "title": "My Top 3 Running Shoes | Marathon Prep Training",
      "thumbnail": "https://i.ytimg.com/vi/z5mWgBMOFJk/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4q…",
      "viewCountText": "682,786 views",
      "viewCountInt": 682786,
      "publishedTimeText": "6 years ago",
      "publishedTime": "2020-10-01T14:32:05.335Z",
      "lengthText": "17:18",
      "lengthSeconds": 1038,
      "badges": [],
      "description": "Subscribe: http://bit.ly/subNickBare Follow Nick Bare: Facebook: http://…",
      "channel": {
        "id": "UCbVEx9qG_hLrb6FrWQJz_Tg",
        "title": "Nick Bare",
        "handle": "nickbarefitness",
        "url": "https://www.youtube.com/@nickbarefitness",
        "thumbnail": "https://yt3.ggpht.com/ytc/AIdro_mVx6fQ8UNrMx2sjhQ5JwJyQTCfSXAoznqRdRSZLo…"
      }
    },
    {
      "type": "video",
      "id": "GDL5GVlpuko",
      "url": "https://www.youtube.com/watch?v=GDL5GVlpuko",
      "title": "My Complete Guide To Running Shoes! (Everything You Need To Know)",
      "thumbnail": "https://i.ytimg.com/vi/GDL5GVlpuko/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4q…",
      "viewCountText": "282,242 views",
      "viewCountInt": 282242,
      "publishedTimeText": "10 months ago",
      "publishedTime": "2025-12-04T14:32:05.335Z",
      "lengthText": "20:25",
      "lengthSeconds": 1225,
      "badges": [
        "1 product",
        "4K"
      ],
      "description": "If you enjoyed the video, please like, comment and subscribe! Thank you …",
      "channel": {
        "id": "UCZPqG0yh_xPm2AyLjffbDvw",
        "title": "Ben Parkes",
        "handle": "BenParkes",
        "url": "https://www.youtube.com/@BenParkes",
        "thumbnail": "https://yt3.ggpht.com/ytc/AIdro_mDy4ZoQqcj7DiO_-1z6j2Y6Nu_PvFESGAsJagEM5…"
      }
    }
  ],
  "shorts": [
    {
      "type": "short",
      "id": "SVyIXZQABS8",
      "url": "https://www.youtube.com/shorts/SVyIXZQABS8",
      "title": "Which shoes to get for your Hyrox training? Boldfit Running Shoes",
      "thumbnail": "https://i.ytimg.com/vi/SVyIXZQABS8/oar2.jpg?sqp=-oaymwEgCJUDEOAESFWQAgHy…",
      "viewCountText": "44 views",
      "viewCountInt": 44
    },
    {
      "type": "short",
      "id": "rKuu1bK6qQY",
      "url": "https://www.youtube.com/shorts/rKuu1bK6qQY",
      "title": "Best Running Shoes for Long Runs 🏃",
      "thumbnail": "https://i.ytimg.com/vi/rKuu1bK6qQY/oar2.jpg?sqp=-oaymwEgCJUDEOAESFWQAgHy…",
      "viewCountText": "7M views",
      "viewCountInt": 7000000
    }
  ],
  "channels": [],
  "playlists": [],
  "lives": [],
  "continuationToken": "EugBEg1ydW5uaW5nIHNob2VzGtYBU0JTQ0FRdDZOVzFYWjBKTlQwWkthNElCQzBkRVREVkhW…"
}

Response fields

Every field in a successful response, and what it means. A name with [] belongs to each item of a list: videos[].type is the type of every item in videos. null means there's no value.

Show all 77 fields

Field	Type	Description
success	true	Always true here; errors have `success: false`.
credits_remaining	number	Your balance after this call. On anonymous playground calls: free tries left today.
credits_charged	number	Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1).
videos	object[]	Videos, in result order.
videos[].type	"video"	Always `video`.
videos[].id	string	Video id, e.g. `v9QtM6qnG50`.
videos[].url	string	Watch link. Pass it to the video endpoint for likes, comments, the full description and exact views.
videos[].title	string	Video title. YouTube may translate non-English titles into English; video details has the original.
videos[].thumbnail	stringcan be null	Largest thumbnail URL.
videos[].viewCountText	stringcan be null	Views as YouTube shows them, e.g. "82M views", or "1,204 watching" while live.
videos[].viewCountInt	numbercan be null	viewCountText as a number, rounded whenever YouTube abbreviates it (82M views → 82000000). Use video details for exact views.
videos[].publishedTimeText	stringcan be null	When it went up, as YouTube shows it, e.g. "10 days ago". null for live and upcoming videos.
videos[].publishedTime	stringcan be null	publishedTimeText as an estimated ISO 8601 time, counted back from when we fetched the page. Only as precise as the text: "1 year ago" means sometime that year.
videos[].lengthText	stringcan be null	Length as shown, e.g. "19:03". null for live and upcoming videos.
videos[].lengthSeconds	numbercan be null	Length in seconds.
videos[].badges	string[]	Labels YouTube shows on the result, e.g. "4K", "CC", "New" or "LIVE". Often empty.
videos[].description	stringcan be null	The description snippet shown under the result, usually its first line or two.
videos[].channel	objectcan be null	The channel behind it.
videos[].channel.id	stringcan be null	Channel id, `UC…`.
videos[].channel.title	stringcan be null	Channel name.
videos[].channel.handle	stringcan be null	Handle without the @, e.g. `BenParkes`; null if YouTube shows none.
videos[].channel.url	stringcan be null	Channel page, e.g. `https://www.youtube.com/@BenParkes`.
videos[].channel.thumbnail	stringcan be null	Channel picture URL; null when the result doesn't show one.
shorts	object[]	Shorts, in result order.
shorts[].type	"short"	Always `short`.
shorts[].id	string	The Short's video id.
shorts[].url	string	`https://www.youtube.com/shorts/<id>`. Pass it to the video endpoint for likes, comments, date and length.
shorts[].title	string	The Short's title. YouTube may translate non-English titles into English; video details has the original.
shorts[].thumbnail	stringcan be null	Largest (vertical) thumbnail URL.
shorts[].viewCountText	stringcan be null	Views as YouTube shows them, e.g. "22M views".
shorts[].viewCountInt	numbercan be null	viewCountText as a number, rounded as shown (22M views → 22000000).
channels	object[]	Channels, in result order.
channels[].type	"channel"	Always `channel`.
channels[].id	string	Channel id, `UC…`. Pass it to channel details for the full stats.
channels[].url	string	Channel page.
channels[].title	string	Channel name.
channels[].handle	stringcan be null	Handle without the @; null if YouTube shows none.
channels[].thumbnail	stringcan be null	Channel picture URL.
channels[].description	stringcan be null	The description snippet shown in the result.
channels[].subscriberCountText	stringcan be null	Subscribers as YouTube shows them, e.g. "128K subscribers".
channels[].subscriberCount	numbercan be null	subscriberCountText as a number, rounded as shown.
channels[].isVerified	boolean	Has YouTube's verified or official artist badge.
playlists	object[]	Playlists and mixes, in result order.
playlists[].type	"playlist"	Always `playlist`.
playlists[].id	string	Playlist id, e.g. `PLB50X6wE7gSWNQJElg3NX4AH42QoouHOk` (mixes start with `RD`).
playlists[].url	string	Playlist page, `https://www.youtube.com/playlist?list=<id>`.
playlists[].title	string	Playlist title.
playlists[].thumbnail	stringcan be null	Cover thumbnail URL (its first video).
playlists[].videoCountText	stringcan be null	Size as YouTube shows it, e.g. "30 videos".
playlists[].videoCount	numbercan be null	videoCountText as a number.
playlists[].channel	objectcan be null	The channel behind it.
playlists[].channel.id	stringcan be null	Channel id, `UC…`.
playlists[].channel.title	stringcan be null	Channel name.
playlists[].channel.handle	stringcan be null	Handle without the @, e.g. `BenParkes`; null if YouTube shows none.
playlists[].channel.url	stringcan be null	Channel page, e.g. `https://www.youtube.com/@BenParkes`.
playlists[].channel.thumbnail	stringcan be null	Channel picture URL; null when the result doesn't show one.
lives	object[]	Streams that are live right now.
lives[].type	"video"	Always `video`.
lives[].id	string	Video id, e.g. `v9QtM6qnG50`.
lives[].url	string	Watch link. Pass it to the video endpoint for likes, comments, the full description and exact views.
lives[].title	string	Video title. YouTube may translate non-English titles into English; video details has the original.
lives[].thumbnail	stringcan be null	Largest thumbnail URL.
lives[].viewCountText	stringcan be null	Views as YouTube shows them, e.g. "82M views", or "1,204 watching" while live.
lives[].viewCountInt	numbercan be null	viewCountText as a number, rounded whenever YouTube abbreviates it (82M views → 82000000). Use video details for exact views.
lives[].publishedTimeText	stringcan be null	When it went up, as YouTube shows it, e.g. "10 days ago". null for live and upcoming videos.
lives[].publishedTime	stringcan be null	publishedTimeText as an estimated ISO 8601 time, counted back from when we fetched the page. Only as precise as the text: "1 year ago" means sometime that year.
lives[].lengthText	stringcan be null	Length as shown, e.g. "19:03". null for live and upcoming videos.
lives[].lengthSeconds	numbercan be null	Length in seconds.
lives[].badges	string[]	Labels YouTube shows on the result, e.g. "4K", "CC", "New" or "LIVE". Often empty.
lives[].description	stringcan be null	The description snippet shown under the result, usually its first line or two.
lives[].channel	objectcan be null	The channel behind it.
lives[].channel.id	stringcan be null	Channel id, `UC…`.
lives[].channel.title	stringcan be null	Channel name.
lives[].channel.handle	stringcan be null	Handle without the @, e.g. `BenParkes`; null if YouTube shows none.
lives[].channel.url	stringcan be null	Channel page, e.g. `https://www.youtube.com/@BenParkes`.
lives[].channel.thumbnail	stringcan be null	Channel picture URL; null when the result doesn't show one.
continuationToken	stringcan be null	Pass as `continuationToken` for the next page. null on the last page.

Cost and freshness

Each call costs 1 credit. Calls turned away before they reach the platform (invalid parameters, a key or balance problem, a rate limit) are free, and so are 5xx errors. A not_found is charged, since the platform was checked. How charging works.

Answers are cached for up to 15 minutes. A repeat call within that time can return the same data, and costs the same.

Errors

A failed call returns success: false, an error message, a code your program can check, and a docs link. These are the errors this endpoint can return. All error codes.

Status	Code	Meaning
401	`missing_api_key`	No API key was sent. Put it in the `x-api-key` header.
401	`invalid_api_key`	This key doesn't exist or was revoked.
402	`insufficient_credits`	Not enough credits for this call. Buy a pack, or wait for tomorrow's free top-up.
402	`over_max_credits`	This call would cost more than the `max_credits` you set. The error says what it needs; raise `max_credits` to allow it. Not charged.
403	`account_suspended`	This account is suspended. Email support@lurkapi.com. Not charged.
405	`method_not_allowed`	Endpoints only take `GET`, with parameters in the URL.
429	`rate_limited`	Too many calls in a short time. Wait as many seconds as the `retry-after` header says, then retry.
500	`internal_error`	Something broke on our side. Retry. Not charged.
502	`upstream_error`	The platform didn't send a usable answer. Retry. Not charged.
503	`upstream_busy`	All our connections to the platform are busy. Retry in a few seconds. Not charged.
504	`upstream_timeout`	The platform took over 30 seconds to answer (90 for web pages). Retry. Not charged.

Use it in Claude

Connect LurkAPI to Claude and ask in plain English. This endpoint is the youtube_search tool. For example:

Ask Claude

Use LurkAPI's youtube_search tool with query "running shoes", then summarize what you find.

Claude calls youtube_search with arguments like these, and each call costs 1 credit:

Tool arguments

{"query": "running shoes"}

To save tokens, tool results leave out empty fields, keep one URL per image or video, and give transcripts as plain text unless you pass timestamps=true. A result over 45,000 characters comes in parts. Its _note gives the offset for the next part, and later parts are free for 15 minutes. Pass trim=false for the full response.

From the blog

All posts