Search YouTube
Search public YouTube videos by keyword or topic. Narrow results to an upload-date window and choose how they are ordered — by relevance (default), newest first, most-viewed or highest-rated.
GET /v1/youtube/search
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | — | Required. Keyword(s) or topic, e.g. electric cars. |
filter | string | videos | Result type: videos or shorts. |
uploaded_within | string | — | Restrict to videos uploaded within a period: hour, today, week, month or year. Omit for no date limit. |
sort_by | string | relevance | Result order: relevance, date (newest first), views or rating. |
max_results | integer | 20 | Maximum number of videos to return. Range 1–200. |
Fewer results come back if YouTube has no more matches.
Examples
Basic keyword search:
curl -G "$LISTENX_BASE/v1/youtube/search" \
-H "X-API-Key: $LISTENX_KEY" \
--data-urlencode 'query=electric cars'
Shorts only, up to 50 results:
curl -G "$LISTENX_BASE/v1/youtube/search" \
-H "X-API-Key: $LISTENX_KEY" \
--data-urlencode 'query=spacex launch' \
--data-urlencode 'filter=shorts' \
--data-urlencode 'max_results=50'
Newest uploads from the past week:
curl -G "$LISTENX_BASE/v1/youtube/search" \
-H "X-API-Key: $LISTENX_KEY" \
--data-urlencode 'query=spacex launch' \
--data-urlencode 'uploaded_within=week' \
--data-urlencode 'sort_by=date'
Response
{
"query": "electric cars",
"filter": "videos",
"uploaded_within": null,
"sort_by": "relevance",
"requested": 20,
"returned": 20,
"results": [
{
"type": "video",
"video_id": "abc123XYZ01",
"url": "https://www.youtube.com/watch?v=abc123XYZ01",
"title": "The best electric cars of 2026",
"channel": "Auto Review",
"channel_id": "UC000000000000000000001",
"duration": "14:32",
"views": 184203,
"views_text": "184K views",
"published_text": "3 weeks ago",
"published_at": "2026-10-20T00:00:00+00:00",
"thumbnail": "https://i.ytimg.com/vi/abc123XYZ01/hqdefault.jpg",
"description": "We rank this year's top EVs on range, price and charging…"
}
],
"billing": {
"endpoint": "youtube.search",
"units": 1,
"unit_price": "0.010000",
"amount": "0.010000",
"balance_after": "19.990000",
"request_id": "…"
}
}
Fields
| Field | Description |
|---|---|
query | The query you searched for. |
filter | The result type returned (videos or shorts). |
uploaded_within | The upload-date window applied, or null when no date limit was set. |
sort_by | The order applied (relevance, date, views or rating). |
requested | The max_results you asked for. |
returned | Number of videos in results. |
results[] | Video records, in the requested order. |
Each video record carries video_id and channel_id — pass them to the
video and channel endpoints to enrich a
result.
Billing
Search is billed per block of results returned (a block is up to 20 results), minimum 1 unit. See Billing.
Notes
- Search is a discovery surface; results are not exhaustive and can shift over time.
- Shorts are returned with the same record shape as videos.