# YouTube Search API (https://www.socialcrawl.dev/platforms/youtube/search)

> Searches YouTube by keyword. Returns matching videos, shorts, and live streams (an untyped search returns all three; `type` scopes to one kind, including channels and playlists). Each video result includes title, URL, thumbnail, view count, publish date, duration, channel info, and badges. For Shorts results, exact publish dates and durations require `includeExtras=true`.

TL;DR: `GET /v1/youtube/search` costs 1 credit per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search keyword or phrase. |
| `uploadDate` | no | Upload date filter. Reliable on its own (no `type`). With `type=shorts`, windows narrower than `this_year` are rejected with a 400 because YouTube returns an empty set for them; `this_year` is accepted but measured to return ~5x fewer unique Shorts across a paginated walk (the upstream re-serves the same items under an advancing `continuationToken`), so the recommended pattern for Shorts recency is no `uploadDate` at all plus `includeExtras=true` and a client-side filter on `post.published_at`. With other `type` values the upstream currently ignores the date filter and may mix content kinds; filter client-side there too. For an EXACT date window rather than these coarse buckets, use `/v1/youtube/search/advanced`, whose `published_after`/`published_before` take RFC-3339 bounds and are genuinely applied. (today \| this_week \| this_month \| this_year) |
| `sortBy` | no | Sort order — relevance or popular. `popular` cannot be combined with `type=shorts` (rejected with a 400 — YouTube serves that combination unreliably); it also caps the page at ~20 results. It is also NOT a strict view-count sort: `popular` is a popularity-weighted ranking, and results do not come back in descending view order. Measured on 4 of 4 test keywords — a `new york` search returned 9.5M, then 502.9M, then 66K views in that order. If you need a view-faithful ordering, use `/v1/youtube/search/advanced` with `order=viewCount` and `includeExtras=true` — its ranking leads with the true top results, and the returned `engagement.views` lets you sort the page exactly client-side. (relevance \| popular) |
| `type` | no | Type of content to return. (videos \| shorts \| channels \| playlists) |
| `duration` | no | Video duration filter. KNOWN UPSTREAM ISSUE: currently not applied by the provider and it can degrade the `type` filter; prefer filtering client-side on `post.content.duration_seconds`. (under_3_min \| between_3_and_20_min \| over_20_min) |
| `region` | no | 2-letter country code of the country to put the proxy in. |
| `continuationToken` | no | Continuation token to get more results. Get `continuationToken` from a previous response. |
| `includeExtras` | no | Set to `true` to add the like count and comment count (`post.engagement.likes` / `.comments`) and the video description (`post.ext.description`) to each video result. Left off, those three are null. For Shorts results it also supplies `post.published_at` and `post.content.duration_seconds` — Shorts items carry neither without it, so recency filtering over `type=shorts` requires this flag. Slows the response slightly. For full per-video details use `/v1/youtube/video`. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/youtube/search?query=javascript%20tutorial" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I search YouTube with a keyword via API?

Send a GET request to /v1/youtube/search with query=your keyword. The response is a list of matching videos with titles, view counts, channel info, thumbnails, and publish dates.

### Can I filter search results by upload date?

Yes. Pass uploadDate=today, this_week, this_month, or this_year to narrow results. Combine with sortBy=popular to find the most-viewed videos uploaded this week, for example.

### How do I only search for YouTube Shorts?

Pass filter=shorts in the query parameters. Note the filter only works when you search by keyword. It's incompatible with uploadDate and sortBy, which apply to long-form results.

### Can I search from a specific country's perspective?

Yes. Pass region=US, region=KR, region=GB, or any 2-letter country code to route the request through a proxy in that country. This surfaces regionally ranked results.

### Do I need the YouTube Data API for search?

No. SocialCrawl's search endpoint does not consume Google Cloud quota and does not require an API key from Google. One key, one endpoint, 1 credit per request, no OAuth.

See the full YouTube API: https://www.socialcrawl.dev/platforms/youtube

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to search YouTube videos by keyword without Data API quota
- YouTube search API with upload date and region filters