YouTube Get General Search

2.07 credits/call
ae_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.

VideoSocial
2.07 credits/call

Pricing

2.07 credits/call
ConditionCharge
Each call2.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.

ParameterTypeRequiredDescriptionDefault
featureunknown | nullNo特征过滤 | Feature filter—
sort_byunknown | nullNo排序方式 | Sort by—
durationunknown | nullNo视频时长过滤 | Duration filter—
time_zonestringNo时区(如America/Los_Angeles, Asia/Shanghai等)/Time zoneAmerica/Los_Angeles
upload_timeunknown | nullNo上传时间过滤 | Upload time filter—
content_typeunknown | nullNo内容类型过滤 | Content type filter—
country_codestringNo国家代码(如US, CN等)/Country codeUS
search_querystringYes搜索关键字/Search keyword—
language_codestringNo语言代码(如zh-CN, en-US等)/Language codezh-CN
continuation_tokenstring | nullNo翻页令牌/Pagination token—

Invocation example

Copy the request and explore its response example.

POST/agent-api/v1/tool/executeX-Api-Key
Request coderequest.sh
curl --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"
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "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.