Searching Through Videos
Learn how to use natural language to search for specific moments within a single video or across a library of videos.
Overview
VidNavigator supports two distinct search workflows: global platform search discovers videos on YouTube or TikTok, while semantic (vector) search finds relevant information in already indexed YouTube channel content and uploaded files.
Prerequisites
- A valid VidNavigator API key.
- The Python or JavaScript SDK, version 2.1.0 (
pip install vidnavigator==2.1.0ornpm install vidnavigator@2.1.0).
Billing
Billing depends on which search you run:
- Semantic search over indexed content consumes one
search_requestper call. This includes indexed YouTube channel search and file search (/search/file); file search can also billanalysis_requestif the AI analysis pass runs. 1 credit covers 1,000 semantic searches. - Global YouTube search (
/youtube/search) does not billsearch_request. It bills oneresidential_requestper candidate video analyzed, plus a single consolidatedanalysis_request(ceil(total_tokens / 15000)). See Search YouTube. - TikTok keyword search (
/tiktok/search) does not billsearch_request; it bills per residential page fetched. See TikTok Search.
Searching Videos
Searching Across YouTube
This example searches YouTube for videos that match a query, via the /youtube/search endpoint. The results are ranked with an AI analysis of each video's transcript.
from vidnavigator import VidNavigatorClient, VidNavigatorError
client = VidNavigatorClient() # reads VIDNAVIGATOR_API_KEY
try:
results = client.search_youtube(
query="What are the best practices for React development?",
focus="relevance",
start_year=2022,
max_results=5, # caps how many candidates are analyzed, and the cost
)
print(f"Found {results.data.total_found} relevant videos:")
for video in results.data.results:
print(f"- {video.title} ({video.url}), score: {video.relevance_score}")
print(f" {video.transcript_summary}")
except VidNavigatorError as e:
print(f"An error occurred: {e}")focus decides what comes first among the videos that match: relevance (default), recency (the most recent), popularity (the most viewed) or brevity (the shortest). start_year and end_year bound the publication year, and duration is a maximum length in seconds.
search_videos / searchVideos still work in the 2.1.0 SDKs as deprecated aliases. Use search_youtube / searchYouTube in new code.
Searching Your Uploaded Files
This example searches across the files you have uploaded to VidNavigator. Each result includes namespace_ids and namespaces showing which namespaces the file belongs to, plus the timestamps where the matching content appears.
try:
results = client.search_files(query="Customer feedback on pricing")
print(f"Found {results.data.total_found} relevant files:")
for file_result in results.data.results:
ns_names = [ns.name for ns in file_result.namespaces or []]
print(f"- {file_result.name} (score: {file_result.relevance_score}, namespaces: {ns_names})")
print(f" Timestamps: {file_result.timestamps}")
except VidNavigatorError as e:
print(f"An error occurred: {e}")Filtering File Search by Namespace
You can restrict search to specific namespaces by passing namespace_ids. If omitted, all namespaces are searched.
results = client.search_files(
query="Customer feedback on pricing",
namespace_ids=["64a1b2c3d4e5f6789abc0002"],
)Next Steps
- Search TikTok by keyword or collect a creator's videos: Searching TikTok.
- Upload your own recordings to make them searchable: Uploading and Processing Files.