YouTube Get General Search
Search YouTube by keyword and optionally narrow results by upload time, video duration, content type, or feature, with configurable sorting and regional settings. Inputs: - search_query (required): search keywords, up to 200 characters. - language_code: language code such as zh-CN or en-US; default zh-CN. - country_code: country code affecting regional relevance, such as US or CN; default US. - time_zone: time zone such as America/Los_Angeles or Asia/Shanghai; default America/Los_Angeles. - upload_time: hour (past hour), today, week (this week), month (this month), or year (this year). - duration: short (under 4 minutes), medium (4–20 minutes), or long (over 20 minutes). - content_type: video, channel, playlist, or movie. - feature: live, 4k, hd, subtitles, creative_commons, 360, vr180, 3d, hdr, location, or purchased. - sort_by: relevance (documented default), upload_date, view_count, or rating. - continuation_token: optional pagination token for another page; use a token returned by an earlier search when available. All inputs except search_query are optional. Choose at most one value per filter; filter fields can be combined. Returns the search response directly, with raw YouTube search data in data. The result structure requires parsing and is not a standardized list of video, channel, or playlist records; specific item fields are not guaranteed. This tool searches for content rather than downloading it. Example: search_query="Python tutorial", upload_time="week", duration="short", content_type="video" searches for short Python tutorial videos uploaded this week.
Pricing
| Condition | Charge |
|---|---|
| Each call | 2.07 credits/call |
Each YouTube keyword search call has a fixed charge of 2.07 credits. Charges are per query. A successful query is billed even if it returns no results.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
feature | unknown | null | No | 特征过滤 | Feature filter | — |
sort_by | unknown | null | No | 排序方式 | Sort by | — |
duration | unknown | null | No | 视频时长过滤 | Duration filter | — |
time_zone | string | No | 时区(如America/Los_Angeles, Asia/Shanghai等)/Time zone | America/Los_Angeles |
upload_time | unknown | null | No | 上传时间过滤 | Upload time filter | — |
content_type | unknown | null | No | 内容类型过滤 | Content type filter | — |
country_code | string | No | 国家代码(如US, CN等)/Country code | US |
search_query | string | Yes | 搜索关键字/Search keyword | — |
language_code | string | No | 语言代码(如zh-CN, en-US等)/Language code | zh-CN |
continuation_token | string | null | No | 翻页令牌/Pagination token | — |
Invocation example
Copy the request and explore its response example.
/agent-api/v1/tool/executeX-Api-Keycurl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_youtube_get_general_search' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"content_type": "video",
"country_code": "ES",
"language_code": "es-ES",
"search_query": "fútbol español",
"sort_by": "upload_date",
"time_zone": "Europe/Madrid",
"upload_time": "week"
}
}'{
"detail": {
"code": 400,
"docs": "https://api.tikhub.io/#/YouTube-Web-V2-API/get_general_search_api_v1_youtube_web_v2_get_general_search_get",
"headers": {},
"message": "Request failed. Please retry. Check the docs below to verify your parameters, test with the default demo parameters, and send the response JSON to support. You won't be charged for this request.",
"message_zh": "请求失败,请重试。请查看下方文档核对参数,使用默认演示参数测试,并将响应 JSON 提交给支持团队。本次请求不会被扣费。",
"params": {
"content_type": "video",
"country_code": "ES",
"language_code": "es-ES",
"search_query": "fútbol español",
"sort_by": "upload_date",
"time_zone": "Europe/Madrid"
}
}
}This example shows part of the response. Copied content is valid JSON.

