YouTube Video Details
Read everything YouTube knows about videos of the connected channel: privacy and processing status, duration, statistics, translations, recording date, paid product placement, topics and, for your own videos, file details and YouTube's suggestions. Use it to check an upload or to verify an edit.
Endpoint
GET /api/uploadposts/youtube/videos
Headers
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
Query Parameters
Send user and exactly one of ids, chart or my_rating.
| Name | Type | Required | Description |
|---|---|---|---|
user | String | Yes | Profile username with a YouTube channel connected. |
ids | String | One of | Up to 50 video IDs, comma separated. |
chart | String | One of | mostPopular: YouTube's most popular videos (Trending Music, Movies and Gaming). |
my_rating | String | One of | like or dislike: videos the channel rated (YouTube returns the 1,000 most recent). |
parts | String | No | Comma-separated subset of snippet, status, contentDetails, statistics, processingDetails, localizations, recordingDetails, paidProductPlacementDetails, topicDetails, brandPartner, player, liveStreamingDetails. Default: all but processingDetails and the last three. |
include_owner_details | Boolean | No | Adds processingDetails, fileDetails and suggestions (only for videos of your channel). |
hl | String | No | Language for snippet.localized (e.g. es). |
region_code | String | No | With chart: country (ISO 3166-1, e.g. ES). |
video_category_id | String | No | With chart: category ID. |
max_results | Integer | No | With chart or my_rating: 1-50 (YouTube's default is 5). |
page_token | String | No | With chart or my_rating: the next_page_token of the previous page. |
Example Request
curl -G https://api.upload-post.com/api/uploadposts/youtube/videos \
-H 'Authorization: Apikey your-api-key-here' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'ids=dQw4w9WgXcQ,abc123def45' \
--data-urlencode 'include_owner_details=true'
Successful Response (200 OK)
The items are YouTube's video resources as YouTube returns them (field reference).
{
"success": true,
"items": [
{
"id": "dQw4w9WgXcQ",
"snippet": {"title": "My video", "defaultLanguage": "en", "categoryId": "22"},
"status": {"privacyStatus": "public", "uploadStatus": "processed", "license": "youtube"},
"processingDetails": {"processingStatus": "succeeded"},
"statistics": {"viewCount": "1200", "likeCount": "40", "commentCount": "5"},
"localizations": {"es": {"title": "Mi vídeo", "description": "Descripción"}},
"recordingDetails": {"recordingDate": "2026-10-01T00:00:00Z"},
"paidProductPlacementDetails": {"hasPaidProductPlacement": false}
}
],
"next_page_token": null,
"page_info": {"totalResults": 1, "resultsPerPage": 1},
"not_found": ["abc123def45"]
}
Every list answer of the YouTube endpoints has the same shape: items, next_page_token (null on the last page) and page_info (null when YouTube does not paginate that list).
not_found (only with ids) lists the IDs YouTube did not return: deleted, private to another channel, or wrong.
Daily allowance
YouTube gives every app a daily quota that resets at midnight Pacific Time. Uploads have their own allowance and are never limited by the features on this page. The YouTube management features (video details, the new edit fields and the YouTube endpoints that follow) share a daily allowance per Upload-Post account, measured in YouTube quota units: reading video details costs 1 unit per call; an edit with the new fields costs 51 (a read plus an update).
The daily allowance depends on the plan: 2,000 units on paid plans and 200 on the free plan (searches: 5 and 1 calls). These limits may change.
Check your usage:
curl https://api.upload-post.com/api/uploadposts/youtube/quota \
-H 'Authorization: Apikey your-api-key-here'
{
"success": true,
"enabled": true,
"plan": "paid",
"buckets": {
"general": {"used": 152, "limit": 2000, "unit": "units"},
"search": {"used": 0, "limit": 5, "unit": "calls"},
"batch_stats": {"used": 0, "limit": 200, "unit": "units"}
},
"resets_at": "2026-11-15T08:00:00Z",
"retry_after": 41230
}
Common rules of the YouTube endpoints
These rules apply to every YouTube management endpoint (playlists, captions, comments, channel, live, analytics…):
- Lists always carry
items,next_page_tokenandpage_info(nullwhen there is no paging). - Fields on update: an empty string
""means "no change". A value is removed only withnull(where YouTube allows it) or with the*_removelists. Text fields must be strings: another type is refused with400 invalid_field(the body names thefield) and costs nothing. - Body: a JSON body that does not parse, or is not an object, is refused with
400 invalid_json. - Destructive or hard-to-undo actions need
confirm: true; without it they answer400 confirmation_required("… Send confirm=true to proceed.") and nothing is sent to YouTube. - Writes without an answer: if a write reached YouTube but YouTube did not answer in time, the call answers
502 youtube_write_outcome_unknown. The change may or may not have been applied: check it with the matchingGETbefore sending it again. Upload-Post never resends it on its own, and the units are not given back (YouTube may have charged them). youtube_unreachable(502): YouTube could not be reached or a read did not answer in time. When the request never left (for example the connection could not be opened), the units are given back and it is safe to retry.
Error Responses
All errors carry success: false, a readable error and a stable error_code. Errors that come from YouTube also carry youtube_status (YouTube's HTTP status) and youtube_reason.
- 400 Bad Request —
invalid_filter,too_many_ids,invalid_chart,invalid_rating,invalid_parts,invalid_max_results,missing_user,youtube_not_connected; or YouTube rejected the call (youtube_bad_request,youtube_invalid_page_token, …). - 401 Unauthorized —
youtube_reauth_required: reconnect the YouTube channel. - 403 Forbidden —
youtube_insufficient_scope(reconnect to grant the permission),youtube_forbidden,youtube_channel_unavailable. - 404 Not Found —
youtube_not_found/youtube_video_not_found. - 429 Too Many Requests —
youtube_daily_budget_exhausted(your account used its daily allowance),youtube_shared_budget_exhausted(the allowance shared by all accounts is used up),youtube_quota_exhausted(YouTube's own quota for these requests is used up) oryoutube_rate_limited. The body carriesretry_after(seconds) and, for daily limits,resets_at; theRetry-Afterheader says the same. - 502 Bad Gateway —
youtube_upstream_errororyoutube_unreachable: YouTube did not answer; retry later. - 503 Service Unavailable —
youtube_token_refresh_failed: YouTube did not renew the channel's session right now; retry in a minute (the channel stays connected). - 503 Service Unavailable —
youtube_feature_disabled: YouTube management features are temporarily off. Uploads keep working.