---
title: "Search YouTube for videos on a subject"
method: GET
path: "/search/youtube"
tags: ["Search"]
---

# Search YouTube for videos on a subject

`GET /search/youtube`

## Request

- Base URL: `https://api.socially.run/v1`
- URL: `https://api.socially.run/v1/search/youtube`
- Auth: HTTP bearer

What creators are publishing about a subject, in the order YouTube ranks it: title, channel, exact view count, duration and the description snippet, plus real upload dates, likes and comments when the deployment holds a Data API key (`stats: "exact"`). Read from the results page rather than the API's 100-unit search, so one key's day holds thousands of these. The answer is cached for thirty minutes, and the same question again costs nothing.

## Query parameters

- `q` string, required: What to search for, the way you would type it into YouTube.
- `limit` integer: Videos to return, 1–20. One page is one read: a larger `limit` on the same question is served from it.
- `recency` 'day' | 'week' | 'month' | 'year': Only videos uploaded within the window: `day`, `week`, `month` or `year`. Absent means any time.
- `sort` 'relevance' | 'views': `relevance` uses YouTube's ranking. `views` puts the most-watched videos first. Combine `views` with `recency` to find popular uploads within that window, not to measure growing views. Without a window, `views` includes all-time hits.
- `country` string: The country to rank for, ISO 3166-1 alpha-2 (BR, US, ES). Omit it for YouTube's own ranking rather than a country's.
- `language` string: The language to ask and read the page in, ISO 639-1 (en, pt, es). Omit it and your `accept-language` header decides.
- `refresh` boolean: Read the page again instead of serving the half-hour cache. Charged like any read, and the fresh answer replaces the cached one.

## Response `200`

Search YouTube for videos on a subject

- object
  - `data` unknown, required

## Other responses

- `400`: VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.
- `401`: UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.
- `402`: PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.
- `429`: RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.
- `default`: Any other failure.

---

[API](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json.md) · [All operations](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/llms.txt) · [OpenAPI document](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/revisions/5a0b24534b90?raw)