YouTube Videos API

YouTube Videos

Features

• Known URL batch lookupLook up multiple known public video and Short URLs in one request.
• Stable video identityReturn a stable video ID, canonical URL, title, public description, and publishing channel for every result.
• Content metadataInclude thumbnails, duration, hashtags, publication date, and normalized content type.
• Point-in-time engagement metricsCapture public view, like, and comment counts with collected_at for point-in-time comparison.
• Consistent video schemaProvide the same normalized video structure for regular videos and supported Short URLs.

Parameters

How to Use

Turn a link inbox into records your application can join, search, and refresh. The request is asynchronous, so keep the task ID until every accessible URL has been resolved.

1. Collect and deduplicate public watch or Shorts URLs; channel and search-result URLs belong to other endpoints.
2. POST the urls array to /v1/youtube/videos and store the returned task_id beside your source batch.
3. Poll /v1/tasks/{task_id}; queued and running mean the batch is still being processed.
4. On success, index data.results.items by id and continue with next_cursor while has_more is true.

curl -X POST "https://api.socq.ai/v1/youtube/videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.youtube.com/watch?v=arj7oStGLkU"]}'

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

Best Use Cases

• URL list enrichment: Add titles, channel information, thumbnails, duration, publication dates, and public metrics to an existing list of YouTube URLs.
• Selected video comparison: Compare public views, likes, comments, duration, and publishing information across a chosen set of videos or Shorts.
• Campaign and competitor monitoring: Collect repeated metadata snapshots for known campaign, creator, or competitor videos.
• Content catalogs: Supply normalized video records to internal search, reporting, moderation, summarization, or analytics workflows.

Pro Tips

• Make id your primary key. Titles can change and the same video can arrive through several valid URL formats.
• Keep canonical_url for outbound links, but retain input_url when you need to trace where a record came from.
• Metrics describe the page at collected_at. Comparing two snapshots is useful; overwriting the old one removes that history.
• Treat description links as untrusted external input before rendering, crawling, or importing them.
• A missing result is not proof that a URL never existed. Private, deleted, restricted, or temporarily inaccessible items can disappear from a batch.
• Comments and transcript text are intentionally separate. Request them only for items that reach those stages in your workflow.
• For discovery by topic, begin with Search. Use Videos when you already know which URL matters.

Related APIs