YouTube Search List
1 credits/call
ae_youtube_search_list
Search for YouTube videos, channels, and playlists by keywords, topics, or location.
1 credits/call
Pricing
1 credits/call
| Condition | Charge |
|---|---|
| Each call | 1 credits/call |
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
q | string | No | Textual search terms to match. | — |
part | enum (snippet) | Yes | The *part* parameter specifies a comma-separated list of one or more search resource properties that the API response will include. Set the parameter value to snippet. | — |
type | string | No | Restrict results to a particular set of resource types from One Platform. | — |
order | enum (searchSortUnspecified | date | rating | viewCount | relevance | title | videoCount) | No | Sort order of the results. | — |
forMine | boolean | No | Search for the private videos of the authenticated user. | — |
topicId | string | No | Restrict results to a particular topic. | — |
location | string | No | Filter on location of the video | — |
channelId | string | No | Filter on resources belonging to this channelId. | — |
eventType | enum (none | upcoming | live | completed) | No | Filter on the livestream status of the videos. | — |
pageToken | string | No | Optional opaque pagination token. Omit on the first request. To fetch the next page, copy nextPageToken exactly from the previous response into pageToken and call this same endpoint again, keeping the playlist/channel/video identifiers, filters, part and other query settings unchanged. Use prevPageToken to go back when provided. Do not invent tokens or use a token from another query. Stop when nextPageToken is absent; no nextPageToken means no further page is advertised, even if a page contains fewer items than maxResults. | — |
videoType | enum (videoTypeUnspecified | any | movie | episode) | No | Filter on videos of a specific type. | — |
maxResults | integer | No | Maximum number of items requested per page, not a limit on the total query results. Use nextPageToken as pageToken to retrieve subsequent pages when available. Direct API tests accepted values above 50 but capped the effective page size at 50; requesting more does not increase page size. Zero is accepted and can return an empty page. | — |
regionCode | string | No | Display the content as seen by viewers in this country. | — |
safeSearch | enum (safeSearchSettingUnspecified | none | moderate | strict) | No | Indicates whether the search results should include restricted content as well as standard content. | — |
channelType | enum (channelTypeUnspecified | any | show) | No | Add a filter on the channel search. | — |
forDeveloper | boolean | No | Restrict the search to only retrieve videos uploaded using the project id of the authenticated user. | — |
videoCaption | enum (videoCaptionUnspecified | any | closedCaption | none) | No | Filter on the presence of captions on the videos. | — |
videoLicense | enum (any | youtube | creativeCommon) | No | Filter on the license of the videos. | — |
videoDuration | enum (videoDurationUnspecified | any | short | medium | long) | No | Filter on the duration of the videos. | — |
locationRadius | string | No | Filter on distance from the location (specified above). | — |
publishedAfter | string | No | Filter on resources published after this date. | — |
videoDimension | enum (any | 2d | 3d) | No | Filter on 3d videos. | — |
forContentOwner | boolean | No | Search owned by a content owner. | — |
publishedBefore | string | No | Filter on resources published before this date. | — |
videoCategoryId | string | No | Filter on videos in a specific category. | — |
videoDefinition | enum (any | standard | high) | No | Filter on the definition of the videos. | — |
videoEmbeddable | enum (videoEmbeddableUnspecified | any | true) | No | Filter on embeddable videos. | — |
videoSyndicated | enum (videoSyndicatedUnspecified | any | true) | No | Filter on syndicated videos. | — |
relevanceLanguage | string | No | Return results relevant to this language. | — |
onBehalfOfContentOwner | string | No | *Note:* This parameter is intended exclusively for YouTube content partners. The *onBehalfOfContentOwner* parameter indicates that the request's authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner. | — |
videoPaidProductPlacement | enum (videoPaidProductPlacementUnspecified | any | true) | No | Filter by paid product placement status. Options: videoPaidProductPlacementUnspecified, any, true. | — |
Invocation example
Copy the request and explore its response example.
POST
/agent-api/v1/tool/executeX-Api-KeyRequest coderequest.sh
curl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_youtube_search_list' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"maxResults": 50,
"order": "date",
"part": "snippet",
"publishedAfter": "2026-11-04T16:00:00Z",
"publishedBefore": "2026-11-12T03:03:26.565Z",
"q": "Huawei glasses",
"type": "video"
}
}'Response exampleresponse.json
{
"etag": "Z_vlPJLLIQMWe3e5UYo0E3zR-WA",
"items": [
{
"etag": "HuAJ-U7bH-QPeHE--MWYJljBySs",
"id": {
"kind": "youtube#video",
"videoId": "G7h1xLFwiPM"
},
"kind": "youtube#searchResult",
"snippet": {
"channelId": "UCoZQStUZBYPDytmcyhhRsTA",
"channelTitle": "1 วัน 1000 เรื่องราว",
"description": "รีวิวแว่นตาเสียงอัจฉริยะ (Smart Audio Glasses) ศูนย์ไทยแท้ 2 รุ่นเด่นที่รองรับการตัดเลนส์สายตาจริง ได้แก่ OWNDAYS × HUAWEI Eyewear ...",
"liveBroadcastContent": "none",
"publishTime": "2026-11-11T05:12:00Z",
"title": "แว่น AI EP.6 OWNDAYS vs Xiaomi แว่นเสียงตัดเลนส์"
}
}
],
"kind": "youtube#searchListResponse",
"pageInfo": {
"resultsPerPage": 2,
"totalResults": 54
},
"regionCode": "SG"
}This example shows part of the response. Copied content is valid JSON.

