Skip to the content
EnrichedNowDocs

    Type to search every page.

    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.

    Inputs of youtube.search
    FieldTypeDescription
    queryrequiredstringWhat to search YouTube for.Limit: at least 1 characters, at most 200 characters.
    max_resultsintegerThe 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.

    Record fields of youtube.search
    FieldTypeNotes
    type"video" | "short" | "channel" | "playlist"Always present.
    positionintegerIts place on the page, from 1, counting every result returned.
    idstringThe video id, channel id (UC…) or playlist id.
    urlstringAlways present.
    titlestring or nullnull when not known.
    channel_namestring or nullThe channel that published it; for a channel result, the channel itself.
    channel_idstring or nullnull when not known.
    channel_urlstring or nullnull when not known.
    channel_handlestring or null@name, when the page links the channel by its handle.
    channel_verifiedboolean or nullThe channel shows a verified or official-artist badge; null where the result names no channel.
    published_textstring or nullWhen it was published, as shown ("11y ago").
    duration_textstring or nullThe length as shown ("12:44").
    duration_secondsinteger or nullnull when not known.
    view_count_textstring or nullThe views as shown ("10,140,636 views", "511K views").
    view_countinteger or nullThe views as a number, when the text reads as one.
    view_count_exactboolean or nullTrue when YouTube showed the count in full, false when it showed it rounded (511K).
    is_liveboolean or nullA live stream that is on air now.
    live_viewersinteger or nullPeople watching now, for a live stream.
    subscriber_count_textstring or nullFor a channel: its subscribers as shown ("71.1K subscribers").
    subscriber_countinteger or nullFor a channel: the shown figure as a number (YouTube rounds it to three figures).
    video_count_textstring or nullFor a playlist or a channel: its number of videos as shown ("80 videos", "16 lessons").
    video_countinteger or nullnull when not known.
    description_snippetstring or nullThe lines of description shown under the result.
    badgesarray of stringThe labels shown on the result ("LIVE", "New", "4K", "CC").
    thumbnailsarray of object

    Example request

    Shell
    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:

    JSON
    {
      "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.

    JSON
    {
      "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):

    JSON
    {
      "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.