Scraper · YouTube
youtube.search
Search YouTube: the videos, Shorts, channels and playlists on the first page of results for a query.
- Id
youtube.search- Version
- 1
- Billed per
- record — 1 unit for each record of a charged run
- Runs
- within one request
Start it with POST /v1/scrapers/youtube.search/runs. How runs work is in Running a scraper; what a run costs is in Usage and units.
Inputs
The fields of input. A field that is not listed here is refused.
| Field | Type | Description |
|---|---|---|
queryrequired | string | What to search YouTube for.Limit: at least 1 characters, at most 200 characters. |
max_results | integer | The most results to return. Only the first page of results is read (about 20, plus Shorts), so fewer may come back.Limit: 1 to 50. Default: 20. |
type | "video" | "channel" | "playlist" | "short" | Only results of this kind (YouTube's own Type filter). Leave out for the mixed results YouTube shows by default. |
- Only the first page of results is read.
Record fields
Every record of a run has these fields. A value that is not known is null — never an empty string and never 0.
| Field | Type | Notes |
|---|---|---|
type | "video" | "short" | "channel" | "playlist" | Always present. |
position | integer | Its place on the page, from 1, counting every result returned. |
id | string | The video id, channel id (UC…) or playlist id. |
url | string | Always present. |
title | string or null | null when not known. |
channel_name | string or null | The channel that published it; for a channel result, the channel itself. |
channel_id | string or null | null when not known. |
channel_url | string or null | null when not known. |
channel_handle | string or null | @name, when the page links the channel by its handle. |
channel_verified | boolean or null | The channel shows a verified or official-artist badge; null where the result names no channel. |
published_text | string or null | When it was published, as shown ("11y ago"). |
duration_text | string or null | The length as shown ("12:44"). |
duration_seconds | integer or null | null when not known. |
view_count_text | string or null | The views as shown ("10,140,636 views", "511K views"). |
view_count | integer or null | The views as a number, when the text reads as one. |
view_count_exact | boolean or null | True when YouTube showed the count in full, false when it showed it rounded (511K). |
is_live | boolean or null | A live stream that is on air now. |
live_viewers | integer or null | People watching now, for a live stream. |
subscriber_count_text | string or null | For a channel: its subscribers as shown ("71.1K subscribers"). |
subscriber_count | integer or null | For a channel: the shown figure as a number (YouTube rounds it to three figures). |
video_count_text | string or null | For a playlist or a channel: its number of videos as shown ("80 videos", "16 lessons"). |
video_count | integer or null | null when not known. |
description_snippet | string or null | The lines of description shown under the result. |
badges | array of string | The labels shown on the result ("LIVE", "New", "4K", "CC"). |
thumbnails | array of object |
Example request
curl -X POST "https://api.enrichednow.com/v1/scrapers/youtube.search/runs?wait=60" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"query":"how to fix a flat bike tire"}}'The body on its own:
{
"input": {
"query": "how to fix a flat bike tire"
}
}Example response
The run, once it has ended. A run that has not ended within wait comes back with 202 and the status queued or running.
{
"id": "run_6cce2b12aaf37a10b5e1b885",
"scraper_id": "youtube.search",
"scraper_version": 1,
"status": "ok",
"reason": null,
"input": {
"query": "how to fix a flat bike tire"
},
"record_count": 1,
"units": 1,
"diagnostics": {
"requests": 1,
"bytes": 232779,
"wall_ms": 565,
"facts": {}
},
"created_at": "2026-11-16T20:27:29.009834Z",
"started_at": "2026-11-16T20:27:29.013803Z",
"finished_at": "2026-11-16T20:27:29.582787Z"
}Its records, from GET /v1/runs/{id}/records (the values are an illustration; the fields are the ones above):
{
"records": [
{
"type": "video",
"position": 0,
"id": "string",
"url": "string",
"title": null,
"channel_name": null,
"channel_id": null,
"channel_url": null,
"channel_handle": null,
"channel_verified": null,
"published_text": null,
"duration_text": null,
"duration_seconds": null,
"view_count_text": null,
"view_count": null,
"view_count_exact": null,
"is_live": null,
"live_viewers": null,
"subscriber_count_text": null,
"subscriber_count": null,
"video_count_text": null,
"video_count": null,
"description_snippet": null,
"badges": [],
"thumbnails": []
}
],
"next_cursor": null
}A run does not always end ok. Results and statuses lists every status and the reasons every scraper shares.