Search YouTube
Search YouTube for videos using AI analysis and ranking with optional filters.
Process:
- Enhanced search with prompt engineering to find relevant videos
- AI analysis of video content and transcripts (per-video residential proxy fetch + per-video LLM analysis)
- Intelligent ranking based on query relevance
- Structured results with rich metadata
Billing: for each candidate video the API bills one residential_request when fetching the transcript — set max_results to cap how many candidates are processed and therefore how many residential charges fire. After all per-video AI analyses AND the ranking step complete, a single consolidated analysis_request charge is recorded with quantity = ceil(total_tokens / 15000), where total_tokens is the sum of LLM input + output tokens across all videos 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 the user runs 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/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
- Enhanced query processing: AI expands and optimizes your search query
- Content analysis: per-video transcript fetch (residential proxy) + per-video AI analysis
- Intelligent ranking: results ranked by relevance, not just keyword matching
- Rich results: detailed video information with explanations
Billing
Unlike a flatsearch_request, YouTube search bills for the work it actually does:
- One
residential_requestper candidate video whose transcript is fetched. Usemax_resultsto cap how many candidates are processed — that directly caps how many residential charges fire. - One consolidated
analysis_requestcharge after all per-video analyses and the ranking step complete, withquantity = ceil(total_tokens / 15000)wheretotal_tokensis the sum of LLM input + output tokens across every video analyzed plus the ranking call. - No
search_requestis billed — the residential fetches + analysis fully cover the workflow. - If the search returns zero results, nothing is billed.
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.
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
Year Filtering
Duration Filtering
Focus Types
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query |
use_enhanced_search | boolean | No | Whether to use enhanced search (default true) |
start_year | integer | No | Filter by start year |
end_year | integer | No | Filter by end year |
focus | string | No | relevance (default), popularity, or brevity |
duration | integer | No | Maximum duration in seconds |
max_results | integer | No | Maximum 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_usage | boolean | No | When true, the response includes a usage block listing every meter charged, the total credits deducted, and the remaining balance. |
Example Usage
Response Example
usage block is only included when include_usage=true in the request.Partial Results (402)
Use Cases
Research & Learning
Content Curation
Competitive Analysis
Trend Discovery
Authorizations
API key authentication. Include your VidNavigator API key in the X-API-Key header.
Body
Search query
"What are the best practices for React development?"
Whether to use enhanced search
Filter by start year
2020
Filter by end year
2024
Search focus
relevance, popularity, brevity Maximum duration in seconds
600
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.
x >= 12
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
success 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.

