Skip to Content

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.0 or npm install vidnavigator@2.1.0).

Billing

Billing depends on which search you run:

  • Semantic search over indexed content consumes one search_request per call. This includes indexed YouTube channel search and file search (/search/file); file search can also bill analysis_request if the AI analysis pass runs. 1 credit covers 1,000 semantic searches.
  • Global YouTube search (/youtube/search) does not bill search_request. It bills one residential_request per candidate video analyzed, plus a single consolidated analysis_request (ceil(total_tokens / 15000)). See Search YouTube.
  • TikTok keyword search (/tiktok/search) does not bill search_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

On this page