Skip to main content
POST
/
youtube
/
search
Search YouTube for videos
curl --request POST \
  --url https://api.vidnavigator.com/v1/youtube/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "What are the best practices for React development?",
  "use_enhanced_search": true,
  "start_year": 2020,
  "end_year": 2024,
  "focus": "relevance",
  "duration": 600,
  "max_results": 2,
  "include_usage": false
}
'
import requests

url = "https://api.vidnavigator.com/v1/youtube/search"

payload = {
"query": "What are the best practices for React development?",
"use_enhanced_search": True,
"start_year": 2020,
"end_year": 2024,
"focus": "relevance",
"duration": 600,
"max_results": 2,
"include_usage": False
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What are the best practices for React development?',
use_enhanced_search: true,
start_year: 2020,
end_year: 2024,
focus: 'relevance',
duration: 600,
max_results: 2,
include_usage: false
})
};

fetch('https://api.vidnavigator.com/v1/youtube/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vidnavigator.com/v1/youtube/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What are the best practices for React development?',
'use_enhanced_search' => true,
'start_year' => 2020,
'end_year' => 2024,
'focus' => 'relevance',
'duration' => 600,
'max_results' => 2,
'include_usage' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.vidnavigator.com/v1/youtube/search"

payload := strings.NewReader("{\n \"query\": \"What are the best practices for React development?\",\n \"use_enhanced_search\": true,\n \"start_year\": 2020,\n \"end_year\": 2024,\n \"focus\": \"relevance\",\n \"duration\": 600,\n \"max_results\": 2,\n \"include_usage\": false\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/youtube/search")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What are the best practices for React development?\",\n \"use_enhanced_search\": true,\n \"start_year\": 2020,\n \"end_year\": 2024,\n \"focus\": \"relevance\",\n \"duration\": 600,\n \"max_results\": 2,\n \"include_usage\": false\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.vidnavigator.com/v1/youtube/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What are the best practices for React development?\",\n \"use_enhanced_search\": true,\n \"start_year\": 2020,\n \"end_year\": 2024,\n \"focus\": \"relevance\",\n \"duration\": 600,\n \"max_results\": 2,\n \"include_usage\": false\n}"

response = http.request(request)
puts response.read_body
{
  "status": "success",
  "data": {
    "results": [
      {
        "title": "<string>",
        "url": "<string>",
        "description": "<string>",
        "thumbnail": "<string>",
        "channel": "<string>",
        "published_date": "<string>",
        "duration": 123,
        "views": 123,
        "likes": 123,
        "relevance_score": 123,
        "transcript_summary": "<string>",
        "people": [
          {
            "name": "<string>",
            "context": "<string>"
          }
        ],
        "places": [
          {
            "name": "<string>",
            "context": "<string>"
          }
        ],
        "key_subjects": [
          {
            "name": "<string>",
            "description": "<string>"
          }
        ],
        "timestamp": 123,
        "relevant_text": "<string>",
        "query_relevance": "<string>"
      }
    ],
    "query": "<string>",
    "total_found": 123,
    "explanation": "<string>"
  },
  "usage": {
    "charges": [
      {
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}
{
"status": "error",
"error": "<string>",
"message": "<string>"
}
{
"status": "error",
"error": "limit_exceeded",
"error_code": "limit_exceeded",
"message": "<string>"
}
{
"status": "error",
"error": "internal_server_error",
"message": "<string>"
}
Search YouTube for videos using AI-powered analysis and ranking with optional filters.
This endpoint was previously /search/video. It is now /youtube/search and is dedicated to searching YouTube. To search TikTok, use the TikTok Search endpoint. To search your own uploaded files, use Search Files.

Overview

Find the most relevant YouTube videos using natural language queries. Our AI analyzes video content, transcripts, and metadata to deliver precisely ranked results.

Search Process

  1. Enhanced query processing: AI expands and optimizes your search query
  2. Content analysis: per-video transcript fetch (residential proxy) + per-video AI analysis
  3. Intelligent ranking: results ranked by relevance, not just keyword matching
  4. Rich results: detailed video information with explanations

Billing

Unlike a flat search_request, YouTube search bills for the work it actually does:
  • One residential_request per candidate video whose transcript is fetched. Use max_results to cap how many candidates are processed — that directly caps how many residential charges fire.
  • One consolidated analysis_request charge after all per-video analyses and the ranking step complete, with quantity = ceil(total_tokens / 15000) where total_tokens is the sum of LLM input + output tokens across every video analyzed plus the ranking call.
  • No search_request is billed — the residential fetches + analysis fully cover the workflow.
  • If the search returns zero results, nothing is billed.
Set include_usage: true to receive the full per-charge breakdown. The consolidated analysis_request entry also carries a nested tokens object reporting prompt_tokens / completion_tokens / total_tokens.
Partial results: if you run out of residential_request credits mid-search, the endpoint returns HTTP 402 with status: "partial", the videos analyzed so far in data.results, and error_code: "insufficient_credits_video_search". The usage block (when include_usage=true) reflects only the charges that succeeded.

Search Options

Enhanced Search

AI-powered query expansion and optimization (recommended)

Year Filtering

Filter results by publication date range

Duration Filtering

Limit results by maximum video duration

Focus Types

Prioritize relevance, popularity, or brevity

Request Parameters

ParameterTypeRequiredDescription
querystringYesSearch query
use_enhanced_searchbooleanNoWhether to use enhanced search (default true)
start_yearintegerNoFilter by start year
end_yearintegerNoFilter by end year
focusstringNorelevance (default), popularity, or brevity
durationintegerNoMaximum duration in seconds
max_resultsintegerNoMaximum number of videos to analyse and return. Each candidate triggers one residential_request and contributes tokens to the consolidated analysis_request charge, so lowering this caps the per-call cost. Defaults to your plan ceiling; values above it are silently clamped.
include_usagebooleanNoWhen true, the response includes a usage block listing every meter charged, the total credits deducted, and the remaining balance.

Example Usage

curl -X POST "https://api.vidnavigator.com/v1/youtube/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the best practices for React development?",
    "use_enhanced_search": true,
    "start_year": 2020,
    "end_year": 2024,
    "focus": "relevance",
    "duration": 1800,
    "max_results": 5
  }'
import requests

url = "https://api.vidnavigator.com/v1/youtube/search"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "query": "What are the best practices for React development?",
    "use_enhanced_search": True,
    "start_year": 2020,
    "end_year": 2024,
    "focus": "relevance",
    "duration": 1800,
    "max_results": 5
}

response = requests.post(url, headers=headers, json=data)
results = response.json()

for video in results['data']['results']:
    print(f"Title: {video['title']}")
    print(f"Relevance Score: {video['relevance_score']}")
const response = await fetch('https://api.vidnavigator.com/v1/youtube/search', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'What are the best practices for React development?',
    use_enhanced_search: true,
    start_year: 2020,
    end_year: 2024,
    focus: 'relevance',
    duration: 1800,
    max_results: 5
  })
});

const results = await response.json();

Response Example

{
  "status": "success",
  "data": {
    "results": [
      {
        "title": "React Best Practices 2024: Clean Code & Performance",
        "description": "Complete guide to writing maintainable React code...",
        "url": "https://youtube.com/watch?v=example123",
        "thumbnail": "https://img.youtube.com/vi/example123/maxresdefault.jpg",
        "channel": "React Mastery",
        "duration": "15:30",
        "views": 125000,
        "published_date": "2024-01-15",
        "relevance_score": 0.95,
        "explanation": "This video directly addresses React best practices with focus on clean code and performance optimization.",
        "key_topics": ["React hooks", "Performance optimization", "Code organization"]
      }
    ],
    "query": "What are the best practices for React development?",
    "total_found": 1,
    "explanation": "Found videos discussing React development best practices, focusing on recent content and high relevance."
  },
  "usage": {
    "charges": [
      { "service_type": "residential_request", "quantity": 5, "credits": 0.025 },
      {
        "service_type": "analysis_request",
        "quantity": 2,
        "credits": 0.02,
        "tokens": { "prompt_tokens": 24000, "completion_tokens": 4200, "total_tokens": 28200 }
      }
    ],
    "total_credits": 0.045
  }
}
The usage block is only included when include_usage=true in the request.

Partial Results (402)

{
  "status": "partial",
  "error_code": "insufficient_credits_video_search",
  "message": "Ran out of credits after analyzing some videos.",
  "data": {
    "results": [ ... ],
    "query": "...",
    "total_found": 3,
    "explanation": "..."
  },
  "usage": { "charges": [ ... ], "total_credits": 0.02 }
}

Use Cases

Research & Learning

Find educational content on specific topics or technologies

Content Curation

Build curated lists of videos for courses or documentation

Competitive Analysis

Analyze what content exists in your industry or niche

Trend Discovery

Identify trending topics and popular content creators

Authorizations

X-API-Key
string
header
required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json
query
string
required

Search query

Example:

"What are the best practices for React development?"

Whether to use enhanced search

start_year
integer

Filter by start year

Example:

2020

end_year
integer

Filter by end year

Example:

2024

focus
enum<string>
default:relevance

Search focus

Available options:
relevance,
popularity,
brevity
duration
integer

Maximum duration in seconds

Example:

600

max_results
integer

Maximum number of videos to analyse and return. Each candidate triggers one residential_request (transcript fetch) and contributes tokens to the consolidated analysis_request charge, so lowering this caps the per-call cost. When omitted, defaults to the user's plan ceiling (videos_per_search_count). Values above the plan ceiling are silently clamped down.

Required range: x >= 1
Example:

2

include_usage
boolean
default:false

When true, the response includes a usage block listing every meter charged during this request, the total credits deducted, and the user's remaining balance.

Response

Search completed successfully

status
enum<string>
Available options:
success
data
object
usage
object

Per-call usage disclosure. Returned only when the caller passes include_usage=true in the request body. Lists every meter that fired during this request and the credits actually deducted. Multiple charges of the same meter inside one request are consolidated into a single entry (their quantities and credits are summed). When a charge was waived through a cache-hit sponsorship (e.g. NGO), it carries waived: true + credits_saved, and a top-level waived.credits_saved summary appears.

For endpoints that involve LLM analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the consolidated analysis_request charge entry carries a nested tokens object reporting the LLM input/output token tally for the request.