Logo SearchApi

YouTube Autocomplete API Documentation

GET   /api/v1/search?engine=youtube_autocomplete
OpenAPI Initiative Download OpenAPI Spec

The YouTube Autocomplete API returns the suggestions YouTube shows in its search box as you type a query. Pass a suggestion's value as the q of the YouTube Search API, or a channel suggestion's channel.id as the channel_id of the YouTube Channel API.

API Parameters

Search Query

  • Name
    q
    Required
    Required
    Description

    This parameter is used for the terms you want YouTube search suggestions for. Queries can be partial, like "mr bea" or "how to". Up to 100 characters. Emoji and some symbols count as more than one.

Localization

  • Name
    gl
    Required
    Optional
    Description

    The default parameter us defines the country of the search. Check the full list of supported YouTube gl countries.

  • Name
    hl
    Required
    Optional
    Description

    The default parameter en defines the interface language of the search. Check the full list of supported YouTube hl languages.

Engine

  • Name
    engine
    Required
    Required
    Description

    Parameter defines the engine that will be used to retrieve real-time data. To retrieve YouTube search suggestions, it must be set to youtube_autocomplete.

API key

  • Name
    api_key
    Required
    Required
    Description

    The api_key authenticates your requests. Use it as a query parameter (https://www.searchapi.io/api/v1/search?api_key=YOUR_API_KEY) or in the Authorization header (Bearer YOUR_API_KEY).

Zero Data Retention

  • Name
    zero_retention
    Enterprise Only
    Enterprise Only
    Required
    Optional
    Description

    Set this parameter to true to disable all logging and persistent storage. No request parameters, HTML, or JSON responses are stored or logged. Suitable for high-compliance use cases. Debugging and support may be limited while enabled.

API Examples

Full Response

Full Response

Each suggestion has a value and a type. A query YouTube has no suggestions for returns an error.

GET
https://www.searchapi.io/api/v1/search?engine=youtube_autocomplete&q=mr+beast
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "youtube_autocomplete",
  "q": "mr beast"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_PrEjiAiNrfqVeVt2kbJrjA7r",
    "status": "Success",
    "created_at": "2026-10-02T16:12:49Z",
    "request_time_taken": 1.0,
    "parsing_time_taken": 0.02,
    "total_time_taken": 1.02,
    "request_url": null,
    "html_url": "https://www.searchapi.io/api/v1/searches/search_PrEjiAiNrfqVeVt2kbJrjA7r.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_PrEjiAiNrfqVeVt2kbJrjA7r"
  },
  "search_parameters": {
    "engine": "youtube_autocomplete",
    "q": "mr beast",
    "gl": "US",
    "hl": "en"
  },
  "suggestions": [
    {
      "value": "mrbeast",
      "type": "channel",
      "channel": {
        "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "title": "MrBeast",
        "handle": "@MrBeast",
        "link": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
        "thumbnail": "https://yt3.googleusercontent.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJ..."
      },
      "kgmid": "/g/11ffmnm29k"
    },
    {
      "value": "mr beast give me some money",
      "type": "query"
    },
    "..."
  ]
}

Query, Channel and Entity Suggestions

Query, Channel and Entity Suggestions

The type of a suggestion tells what YouTube is suggesting:

  • query A search term, like marques brownlee meta glasses.
  • channel A YouTube channel, like Marques Brownlee. It adds a channel object with the channel's id and link, and can include its title, handle and thumbnail.
  • entity A topic such as a person, band or show, like Marques Houston. It can include a title, subtitle, thumbnail and thumbnail_source, the page the thumbnail is taken from.
GET
https://www.searchapi.io/api/v1/search?engine=youtube_autocomplete&q=marques
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "youtube_autocomplete",
  "q": "marques"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_0KRPSbUhvz9adGh4ucN2sVjW",
    "status": "Success",
    "created_at": "2026-10-05T14:53:56Z",
    "request_time_taken": 0.82,
    "parsing_time_taken": 0.0,
    "total_time_taken": 0.82,
    "request_url": null,
    "html_url": "https://www.searchapi.io/api/v1/searches/search_0KRPSbUhvz9adGh4ucN2sVjW.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_0KRPSbUhvz9adGh4ucN2sVjW"
  },
  "search_parameters": {
    "engine": "youtube_autocomplete",
    "q": "marques",
    "gl": "US",
    "hl": "en"
  },
  "suggestions": [
    {
      "value": "marques brownlee",
      "type": "channel",
      "channel": {
        "id": "UCBJycsmduvYEL83R_U4JriQ",
        "title": "Marques Brownlee",
        "handle": "@mkbhd",
        "link": "https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ",
        "thumbnail": "https://yt3.googleusercontent.com/qu4TmIaYUlS41-dJ9gZ7DUR3nilvmB5_11i6OKSdvNnBNiyOusZP1bMN6ICnuxtjFB..."
      },
      "kgmid": "/m/0zbt_gq"
    },
    {
      "value": "marques houston",
      "type": "entity",
      "title": "Marques Houston",
      "subtitle": "American singer and songwriter",
      "thumbnail": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQDOzbkCBblIVRYHOpfIRzCwIkkKCaNSYpL1Ppp_pEJ_l2i...",
      "thumbnail_source": "https://www.imdb.com/name/nm0396867/",
      "kgmid": "/m/01pl79y"
    },
    {
      "value": "marques brownlee meta glasses",
      "type": "query"
    },
    "..."
  ]
}

Localization

Localization

Use gl and hl to get the suggestions YouTube shows in another country and language.

GET
https://www.searchapi.io/api/v1/search?engine=youtube_autocomplete&gl=GB&hl=en-gb&q=news
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "youtube_autocomplete",
  "q": "news",
  "gl": "GB",
  "hl": "en-gb"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_AxARiRkgz3HDWqjijF17JYF4",
    "status": "Success",
    "created_at": "2026-10-02T16:12:50Z",
    "request_time_taken": 1.61,
    "parsing_time_taken": 0.0,
    "total_time_taken": 1.61,
    "request_url": null,
    "html_url": "https://www.searchapi.io/api/v1/searches/search_AxARiRkgz3HDWqjijF17JYF4.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_AxARiRkgz3HDWqjijF17JYF4"
  },
  "search_parameters": {
    "engine": "youtube_autocomplete",
    "q": "news",
    "gl": "GB",
    "hl": "en-gb"
  },
  "suggestions": [
    {
      "value": "news",
      "type": "query"
    },
    {
      "value": "news today",
      "type": "query"
    },
    "...",
    {
      "value": "newsround",
      "type": "channel",
      "channel": {
        "id": "UCKlqMc-09XZknXO8jsK-15A",
        "title": "Newsround",
        "handle": "@BBCNewsroundOfficial",
        "link": "https://www.youtube.com/channel/UCKlqMc-09XZknXO8jsK-15A",
        "thumbnail": "https://yt3.googleusercontent.com/nX7aNahzyheqv5Y24JsIlaYxZK-FhuYnhwEdT8MQa_6eAjRwIsM-J4nu3O-zVc3dJh..."
      },
      "kgmid": "/m/0315wk"
    },
    "...",
    {
      "value": "the news agents",
      "type": "entity",
      "title": "The News Agents",
      "subtitle": "Daily News podcast",
      "thumbnail": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcTBojHY9gV2CWAhL_AZ2vJTOfdW7Hpypj7g8acr-LCHEGYy...",
      "thumbnail_source": "https://en.wikipedia.org/wiki/The_News_Agents",
      "kgmid": "/g/11t9_vqyk2"
    },
    "..."
  ]
}