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
| Endpoint | YouTube list | Parameters |
|---|---|---|
GET /api/uploadposts/youtube/categories | Video categories of a region | region (two letters from regions, default US), hl, assignable_only (true: only categories a video can use) |
GET /api/uploadposts/youtube/languages | Languages YouTube supports | hl |
GET /api/uploadposts/youtube/regions | Regions (countries) | hl |
GET /api/uploadposts/youtube/abuse-reasons | Reasons for an abuse report | hl |
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).
Search
GET /api/uploadposts/youtube/search
| Name | Type | Required | Description |
|---|---|---|---|
user | String | Yes | Profile username. |
q | String | One of | Search text (up to 500 characters). Supports - (NOT) and | (OR). |
for_mine | Boolean | One of | true: only videos of the connected channel (only type=video). |
channel_id | String | One of | Only results of this channel (UC…). Not with for_mine. |
topic_id | String | One of | YouTube topic, e.g. /m/04rlf (music). |
location + location_radius | String | One of | latitude,longitude and a radius such as 10km (m, km, ft, mi; up to 1000 km). Needs type=video. |
video_category_id | String | One of | Category from categories. Needs type=video. |
type | String | No | video, channel, playlist (comma separated). Default: all. |
order | String | No | relevance (default), date, rating, title, videoCount, viewCount. |
published_after / published_before | String | No | RFC 3339, e.g. 2026-01-01T00:00:00Z. |
region_code | String | No | Country, ISO 3166-1 alpha-2. |
relevance_language | String | No | ISO 639-1 (zh-Hans / zh-Hant for Chinese). |
safe_search | String | No | moderate (default), none, strict. |
channel_type | String | No | any or show. |
event_type | String | No | live, upcoming, completed. Needs type=video. |
video_caption, video_definition, video_dimension, video_duration, video_embeddable, video_license, video_paid_product_placement, video_syndicated, video_type | String | No | YouTube's video filters (values). Need type=video; most are not accepted with for_mine. |
max_results | Integer | No | 0-50 (YouTube's default is 5). |
page_token | String | No | The 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.