AIsa SEO & AI Visibility

Live YouTube Organic Advanced

post_dataforseo_serp_youtube_organic_live

Destructive

Live SERP provides real-time data on the top 20 blocks of YouTube search engine results. These results are specific to the selected location (see the List of Locations) and language (see the List of Languages) settings. for more info please visit 'https://docs.dataforseo.com/v3/serp/youtube/organic/live/advanced/'

Usage-based billing; Default request estimate: $0.002 USD (not a fixed price). Account-specific pricing and final settlement may differ.

Input Schema

Name	Required	Description	Default
`body`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026

changedInput schema / properties / body / items / oneOf

Previous value: -[
-  {
-    "example": [
-      {
-        "keyword": "audi",
-        "language_code": "en",
-        "location_code": 2840
-      }
-    ],
-    "properties": {
-      "block_depth": {
-        "description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance",
-        "type": [
-          "integer",
-          "null"
-        ]
-      },
-      "device": {
-        "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "keyword": {
-        "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article",
-        "type": "string"
-      },
-      "language_code": {
-        "description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "language_name": {
-        "description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "location_code": {
-        "description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
-        "type": [
-          "integer",
-          "null"
-        ]
-      },
-      "location_name": {
-        "description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "os": {
-        "description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "search_param": {
-        "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "tag": {
-        "description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response",
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "block_depth": {
+        "description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "device": {
+        "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "keyword": {
+        "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article",
+        "type": "string"
+      },
+      "language_code": {
+        "description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "language_name": {
+        "description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "location_code": {
+        "description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "location_name": {
+        "description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "os": {
+        "description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "search_param": {
+        "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "tag": {
+        "description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response",
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  }
+]

Changed2 schema fields changedOct 16, 2026

removedInput schema / properties / body / items / anyOf

Removed value: -[
-  {
-    "example": [
-      {
-        "keyword": "audi",
-        "language_code": "en",
-        "location_code": 2840
-      }
-    ],
-    "properties": {
-      "block_depth": {
-        "description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance",
-        "type": [
-          "integer",
-          "null"
-        ]
-      },
-      "device": {
-        "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "keyword": {
-        "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article",
-        "type": "string"
-      },
-      "language_code": {
-        "description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "language_name": {
-        "description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "location_code": {
-        "description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
-        "type": [
-          "integer",
-          "null"
-        ]
-      },
-      "location_name": {
-        "description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "os": {
-        "description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "search_param": {
-        "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "tag": {
-        "description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response",
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  }
-]

addedInput schema / properties / body / items / oneOf

Added value: +[
+  {
+    "example": [
+      {
+        "keyword": "audi",
+        "language_code": "en",
+        "location_code": 2840
+      }
+    ],
+    "properties": {
+      "block_depth": {
+        "description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "device": {
+        "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "keyword": {
+        "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article",
+        "type": "string"
+      },
+      "language_code": {
+        "description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "language_name": {
+        "description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "location_code": {
+        "description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "location_name": {
+        "description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "os": {
+        "description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "search_param": {
+        "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "tag": {
+        "description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response",
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  }
+]

Changed7 schema fields changedOct 15, 2026

addedInput schema / properties / body / example

Added value: +[
+  {
+    "keyword": "audi",
+    "language_code": "en",
+    "location_code": 2840
+  }
+]

addedInput schema / properties / body / items / anyOf

Added value: +[
+  {
+    "example": [
+      {
+        "keyword": "audi",
+        "language_code": "en",
+        "location_code": 2840
+      }
+    ],
+    "properties": {
+      "block_depth": {
+        "description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "device": {
+        "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "keyword": {
+        "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article",
+        "type": "string"
+      },
+      "language_code": {
+        "description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "language_name": {
+        "description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "location_code": {
+        "description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "location_name": {
+        "description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "os": {
+        "description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "search_param": {
+        "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "tag": {
+        "description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response",
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  }
+]

removedInput schema / properties / body / items / properties

Removed value: -{
-  "keyword": {
-    "description": "Keyword to search for",
-    "type": "string"
-  },
-  "language_code": {
-    "description": "Search engine language code",
-    "type": "string"
-  },
-  "language_name": {
-    "description": "Full name of search engine language",
-    "type": "string"
-  },
-  "location_code": {
-    "description": "Search engine location code",
-    "type": "integer"
-  },
-  "location_name": {
-    "description": "Full name of search engine location",
-    "type": "string"
-  }
-}

removedInput schema / properties / body / items / required
```
Removed value: -[
-  "keyword"
-]
```

changedInput schema / properties / body / items / type

Previous value: -"object"New value: +[
+  "object",
+  "null"
+]

changedInput schema / required

Previous value: -[
-  "body"
-]New value: +[]

addedOutput schema / x-fastmcp-wrap-result
```
Added value: +true
```

Changed7 schema fields changedOct 15, 2026

removedInput schema / properties / body / example

Removed value: -[
-  {
-    "keyword": "audi",
-    "language_code": "en",
-    "location_code": 2840
-  }
-]

removedInput schema / properties / body / items / anyOf

Removed value: -[
-  {
-    "example": [
-      {
-        "keyword": "audi",
-        "language_code": "en",
-        "location_code": 2840
-      }
-    ],
-    "properties": {
-      "block_depth": {
-        "description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance",
-        "type": [
-          "integer",
-          "null"
-        ]
-      },
-      "device": {
-        "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "keyword": {
-        "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article",
-        "type": "string"
-      },
-      "language_code": {
-        "description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "language_name": {
-        "description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "location_code": {
-        "description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
-        "type": [
-          "integer",
-          "null"
-        ]
-      },
-      "location_name": {
-        "description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "os": {
-        "description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "search_param": {
-        "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "tag": {
-        "description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response",
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  }
-]

addedInput schema / properties / body / items / properties

Added value: +{
+  "keyword": {
+    "description": "Keyword to search for",
+    "type": "string"
+  },
+  "language_code": {
+    "description": "Search engine language code",
+    "type": "string"
+  },
+  "language_name": {
+    "description": "Full name of search engine language",
+    "type": "string"
+  },
+  "location_code": {
+    "description": "Search engine location code",
+    "type": "integer"
+  },
+  "location_name": {
+    "description": "Full name of search engine location",
+    "type": "string"
+  }
+}

addedInput schema / properties / body / items / required
```
Added value: +[
+  "keyword"
+]
```

changedInput schema / properties / body / items / type

Previous value: -[
-  "object",
-  "null"
-]New value: +"object"

changedInput schema / required

Previous value: -[]New value: +[
+  "body"
+]

removedOutput schema / x-fastmcp-wrap-result
```
Removed value: -true
```

Changed7 schema fields changedOct 15, 2026

addedInput schema / properties / body / example

Added value: +[
+  {
+    "keyword": "audi",
+    "language_code": "en",
+    "location_code": 2840
+  }
+]

addedInput schema / properties / body / items / anyOf

Added value: +[
+  {
+    "example": [
+      {
+        "keyword": "audi",
+        "language_code": "en",
+        "location_code": 2840
+      }
+    ],
+    "properties": {
+      "block_depth": {
+        "description": "parsing depth\noptional field\nnumber of blocks of results in SERP\ndefault value: 20\nmax value: 200\nNote: your account will be billed per each SERP containing up to 20 results;\nthus, setting a block depth above 20 may result in additional charges if the search engine returns more than 20 results;\nif the specified block depth is higher than the number of results in the response, the difference will be refunded automatically to your account balance",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "device": {
+        "description": "device type\noptional field\nreturn results for a specific device type\navailable values: desktop, mobile",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "keyword": {
+        "description": "keyword\nrequired field\nyou can specify up to 700 characters in the keyword field\nall %## will be decoded (plus character ‘+’ will be decoded to a space character)\nif you need to use the “%” character for your keyword, please specify it as “%25”;\nif you need to use the “+” character for your keyword, please specify it as “%2B”;\nlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article",
+        "type": "string"
+      },
+      "language_code": {
+        "description": "search engine language code\nrequired field if you don't specify language_name\nif you use this field, you don't need to specify language_name\nyou can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nen",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "language_name": {
+        "description": "full name of search engine language\nrequired field if you don't specify language_code\nif you use this field, you don't need to specify language_code\nyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/languages\nexample:\nEnglish",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "location_code": {
+        "description": "search engine location code\nrequired field if you don't specify location_name \nif you use this field, you don't need to specify location_name\nyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\n2840",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "location_name": {
+        "description": "full name of search engine location\nrequired field if you don't specify location_code\nif you use this field, you don't need to specify location_code\nyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/serp/youtube/locations\nexample:\nUnited States",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "os": {
+        "description": "device operating system\noptional field\nif you specify desktop in the device field, choose from the following values: windows, macos\ndefault value: windows\nif you specify mobile in the device field, choose from the following values: android, ios\ndefault value: android",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "search_param": {
+        "description": "additional parameters of the search query\noptional field\nexample:\nsp=EgIQAg%253D%253D",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "tag": {
+        "description": "user-defined task identifier\noptional field\nthe character limit is 255\nyou can use this parameter to identify the task and match it with the result\nyou will find the specified tag value in the data object of the response",
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  }
+]

removedInput schema / properties / body / items / properties

Removed value: -{
-  "keyword": {
-    "description": "Keyword to search for",
-    "type": "string"
-  },
-  "language_code": {
-    "description": "Search engine language code",
-    "type": "string"
-  },
-  "language_name": {
-    "description": "Full name of search engine language",
-    "type": "string"
-  },
-  "location_code": {
-    "description": "Search engine location code",
-    "type": "integer"
-  },
-  "location_name": {
-    "description": "Full name of search engine location",
-    "type": "string"
-  }
-}

removedInput schema / properties / body / items / required
```
Removed value: -[
-  "keyword"
-]
```

changedInput schema / properties / body / items / type

Previous value: -"object"New value: +[
+  "object",
+  "null"
+]

changedInput schema / required

Previous value: -[
-  "body"
-]New value: +[]

addedOutput schema / x-fastmcp-wrap-result
```
Added value: +true
```

First observedSep 15, 2026

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false) are counterintuitive for a data-retrieval endpoint, and the description does not reconcile that tension or mention auth or rate limits. It does add genuinely useful behavioral context the annotations lack: the request is billed per call at roughly $0.002 USD, and higher block_depth may incur extra charges.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core capability is stated in the first sentence, followed by a docs link and a clearly delimited pricing block. It is compact and front-loaded, with only mild boilerplate in the trailing URL and billing lines.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the description covers purpose, location/language dependence, and cost. However, for a paid, multi-field live SERP call it omits which fields are required and when to use it versus the other SERP/social siblings, leaving real gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description generically notes that results are specific to the selected location and language settings, mirroring location_code/language_code, but adds no syntax, defaults, or constraints beyond the schema. The nested field descriptions (os, device, block_depth, keyword encoding rules) already carry that load, so the description contributes little parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it 'provides real-time data on the top 20 blocks of YouTube search engine results', scoped to live SERP with location/language targeting. That is enough to distinguish it from a generic search sibling like get_youtube_search, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to choose this live endpoint over a batch/standard SERP tool, nor any stated prerequisites even though the nested schema marks keyword, and one of location/language, as required. The reader is only told what the results depend on, not when this tool is the right pick.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AIsa SEO & AI Visibility tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?