YouTube Video Search (by Keyword)

{
  "type": "object",
  "required": [
    "search_query"
  ],
  "properties": {
    "order_by": {
      "type": "string",
      "default": "this_month",
      "description": "Order by"
    },
    "country_code": {
      "type": "string",
      "default": "us",
      "description": "Country code"
    },
    "search_query": {
      "type": "string",
      "examples": [
        "Minecraft"
      ],
      "description": "Search keyword"
    },
    "language_code": {
      "type": "string",
      "default": "en",
      "description": "Language code"
    },
    "continuation_token": {
      "type": "string",
      "description": "Pagination token"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "lang": {
      "type": "string",
      "description": "Language code used for the search, e.g. 'en'."
    },
    "query": {
      "type": "string",
      "description": "The search keyword this result set is for."
    },
    "videos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Observed as 'NORMAL' on every video calibrated; other values (e.g. shorts, live) are unconfirmed."
          },
          "title": {
            "type": "string"
          },
          "author": {
            "type": "string",
            "description": "The uploading channel's public display name."
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "Observed `null` on every video in the one real fixture calibrated -- a populated value's shape is unconfirmed."
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Observed empty on every video in the one real fixture calibrated."
          },
          "video_id": {
            "type": "string",
            "description": "The YouTube video id, e.g. 'JCy5R45b7k0'."
          },
          "channel_id": {
            "type": "string",
            "description": "The uploading channel's YouTube channel id."
          },
          "thumbnails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Withheld -- the thumbnail image address is stripped before delivery; only whether a thumbnail exists at that size is observable."
                },
                "width": {
                  "type": "number"
                },
                "height": {
                  "type": "number"
                }
              },
              "additionalProperties": true
            },
            "description": "The same video thumbnail at multiple resolutions."
          },
          "description": {
            "type": "string",
            "description": "The video's own description snippet."
          },
          "video_length": {
            "type": "string",
            "description": "e.g. '19:53', '2:12:13'."
          },
          "published_time": {
            "type": "string",
            "description": "Relative, e.g. '8 days ago', '2 weeks ago' -- not an absolute timestamp."
          },
          "is_live_content": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Observed `null` on every video in the one real fixture calibrated -- whether this is ever populated true/false (for a livestream) is unconfirmed."
          },
          "number_of_views": {
            "type": "number"
          }
        },
        "additionalProperties": true
      },
      "description": "One entry per matching video on this page."
    },
    "country": {
      "type": "string",
      "description": "Country code used for the search, e.g. 'US'."
    },
    "message": {
      "type": "string",
      "description": "A short status message from the search endpoint, present instead of `videos` when a search matches nothing. Observed value: \"Query[...] is not valid\"-style text for a query string the endpoint could not match against anything -- treat its presence as 'no results', not as a thrown error (the call itself still completes and bills normally)."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone the result timestamps are interpreted in, e.g. 'America/New_York'."
    },
    "number_of_videos": {
      "type": "number",
      "description": "Count of videos included in this page of results."
    },
    "estimated_results": {
      "type": "number",
      "description": "The search engine's own estimated total match count across all pages."
    },
    "continuation_token": {
      "type": "string",
      "description": "Opaque pagination token. Pass it back as this tool's `continuation_token` input to fetch the next page of results."
    }
  },
  "description": "The search-result document, as returned at routing.responseResultPath ($.output). Observed with no `videos` field and only a `message` field present when the search query matches no videos -- confirmed against the `nonsense-empty` fixture, which still billed the normal per-call price for that outcome (see usage.md's Cost shape section).",
  "additionalProperties": true
}