Skip to main content

YouTube Search and Catalogs

Search YouTube from the connected channel, and read the lists YouTube uses everywhere else: video categories (for categoryId when you upload or edit), languages, regions and the reasons accepted by an abuse report.

All endpoints need the header Authorization: Apikey your-api-key-here and user (profile username with a YouTube channel connected). They follow the common rules of the YouTube endpoints.

Catalogs​

EndpointYouTube listParameters
GET /api/uploadposts/youtube/categoriesVideo categories of a regionregion (two letters from regions, default US), hl, assignable_only (true: only categories a video can use)
GET /api/uploadposts/youtube/languagesLanguages YouTube supportshl
GET /api/uploadposts/youtube/regionsRegions (countries)hl
GET /api/uploadposts/youtube/abuse-reasonsReasons for an abuse reporthl

hl is the language of the names (one of the languages, e.g. es or es-419; default English). Catalogs change rarely, so Upload-Post keeps a copy for several days: most calls cost nothing ("cached": true). Errors from YouTube are not kept, so the next call asks YouTube again.

curl -G https://api.upload-post.com/api/uploadposts/youtube/categories \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'region=ES' \
--data-urlencode 'hl=es' \
--data-urlencode 'assignable_only=true'
{
"success": true,
"region": "ES",
"hl": "es",
"cached": true,
"items": [
{"id": "22", "snippet": {"title": "Gente y blogs", "assignable": true, "channelId": "UCBR8-60-B28hp2BmDPdntcQ"}}
],
"next_page_token": null,
"page_info": null
}

Errors specific to catalogs: invalid_region, invalid_hl, invalid_assignable_only (400).

GET /api/uploadposts/youtube/search
NameTypeRequiredDescription
userStringYesProfile username.
qStringOne ofSearch text (up to 500 characters). Supports - (NOT) and | (OR).
for_mineBooleanOne oftrue: only videos of the connected channel (only type=video).
channel_idStringOne ofOnly results of this channel (UC…). Not with for_mine.
topic_idStringOne ofYouTube topic, e.g. /m/04rlf (music).
location + location_radiusStringOne oflatitude,longitude and a radius such as 10km (m, km, ft, mi; up to 1000 km). Needs type=video.
video_category_idStringOne ofCategory from categories. Needs type=video.
typeStringNovideo, channel, playlist (comma separated). Default: all.
orderStringNorelevance (default), date, rating, title, videoCount, viewCount.
published_after / published_beforeStringNoRFC 3339, e.g. 2026-01-01T00:00:00Z.
region_codeStringNoCountry, ISO 3166-1 alpha-2.
relevance_languageStringNoISO 639-1 (zh-Hans / zh-Hant for Chinese).
safe_searchStringNomoderate (default), none, strict.
channel_typeStringNoany or show.
event_typeStringNolive, upcoming, completed. Needs type=video.
video_caption, video_definition, video_dimension, video_duration, video_embeddable, video_license, video_paid_product_placement, video_syndicated, video_typeStringNoYouTube's video filters (values). Need type=video; most are not accepted with for_mine.
max_resultsIntegerNo0-50 (YouTube's default is 5).
page_tokenStringNoThe next_page_token of the previous page.
curl -G https://api.upload-post.com/api/uploadposts/youtube/search \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'q=sourdough bread' \
--data-urlencode 'type=video' \
--data-urlencode 'video_duration=short' \
--data-urlencode 'max_results=25'
{
"success": true,
"cached": false,
"items": [
{"id": {"kind": "youtube#video", "videoId": "dQw4w9WgXcQ"},
"snippet": {"title": "Sourdough in 60 seconds", "channelTitle": "Bakery", "publishedAt": "2026-10-02T10:00:00Z"}}
],
"next_page_token": "CBkQAA",
"page_info": {"totalResults": 10000, "resultsPerPage": 25}
}

Searches are scarce. YouTube gives searches a separate allowance that is far smaller than the rest, so each Upload-Post account has a small number of searches per day (see search in the daily allowance), and every page of results is one search. Upload-Post keeps each page for an hour: repeating the same search (same parameters, in any order, any spacing or letter case of q) answers from that copy ("cached": true) and does not use a search. To list the latest videos of a channel, use video details or playlists instead: they do not use searches.

Not available: forDeveloper and the content-owner (CMS) parameters.

Errors specific to search (400): missing_query, invalid_query, invalid_type, invalid_for_mine, invalid_filter, type_video_required, invalid_channel_id, invalid_location, invalid_location_radius, invalid_published_after, invalid_published_before, invalid_region_code, invalid_relevance_language, invalid_topic_id, invalid_video_category_id, invalid_<filter> for an unknown filter value, unsupported_parameter; and 429 youtube_daily_budget_exhausted / youtube_shared_budget_exhausted when no searches are left today (retry_after, resets_at).

The common YouTube errors (401 reconnect, 403, 502, 503 youtube_feature_disabled) are listed in video details.