YouTube Search API

YouTube Search

Features

• URL-free video discoveryDiscover public regular videos without knowing their URLs in advance.
• Result sortingSort results by relevance, publication date, rating, or public view count.
• Publication windowsFilter results by hour, day, week, month, or year publication windows.
• Duration and caption filtersFilter by short, medium, or long duration and require caption availability when needed.
• Normalized video resultsReturn normalized video metadata, channel information, thumbnails, duration, publication data, and public metrics.

Parameters

How to Use

Write the query as a retrieval strategy, not just a keyword. Begin broad enough to inspect the landscape, then add one filter at a time so you can see which decision removed candidates.

1. Define the topic and the question: best topical matches, newest coverage, highly viewed items, or transcript-ready candidates.
2. POST query and results_limit plus only the sort and filters needed for that question to /v1/youtube/search.
3. Store the full request with task_id, then poll /v1/tasks/{task_id} until discovery succeeds or fails.
4. Deduplicate results by video ID, preserve rank context and collected_at, and paginate while has_more is true.

curl -X POST "https://api.socq.ai/v1/youtube/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"NASA Artemis","results_limit":10,"sort_by":"date","published_within":"month","duration":"medium","has_captions":true}'

# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50

Best Use Cases

• Topic and market research: Discover public videos about products, industries, organizations, events, or emerging topics.
• Creator and competitor discovery: Use search results and publishing channel information to identify relevant creators, brands, or competitors.
• Recent video monitoring: Combine date sorting and publication windows to collect recent videos for review or analysis.
• Transcript-ready datasets: Require caption availability to find videos for transcript collection, summarization, classification, or search.

Pro Tips

• Test two or three precise query variants instead of hiding every concept inside one long phrase. The overlap is often as informative as the differences.
• Add filters progressively. If you specify publication window, duration, and captions at once, an empty result gives little clue which constraint was too narrow.
• Use date with published_within for monitoring; relevance with no window answers a different, broader research question.
• Ranking is not stable. Save the request, task ID, video ID, and collected_at whenever the position or composition of the sample matters.
• results_limit is a ceiling, not a completeness guarantee. Public eligibility and the selected filters can yield fewer records.
• Deduplicate across query variants by video ID, but retain which query produced each match for later relevance analysis.
• Once a URL is known, use Videos for refreshed details and Transcripts for available caption text rather than repeatedly searching for it.

Related APIs