Skip to content

Get YouTube Video API: Get YouTube video details

The Get YouTube Video API returns live details for a video on the selected connected YouTube channel. Use the Get YouTube video details operation when you need the current title, description, tags, category, privacy status, and related flags for one video, identified by its account and video ID.

Get YouTube video details: exact GET operation and purpose

This operation returns live details for a video on the selected connected YouTube channel. The exact request is GET {{API_BASE_URL}}/v1/youtube/accounts/{accountId}/videos/{videoId}. Replace only the origin placeholder and the two path values; do not change the method, path segments, casing, or trailing structure. The accountId identifies the connected channel context, and videoId identifies the YouTube video ID to retrieve. Before sending the request, confirm both values are present and that videoId is not empty, because the captured contract requires a length of at least one character. After sending the request, branch on the HTTP status: parse the nested video object on a 200 response, and parse the message field on a 404 or 502 response. Do not assume additional fields beyond those listed in the field maps.

Authorization: x-access-key header

Send the access token in the x-access-key header. The captured authorization contract names the header accessKey, places it in the header, and shows the value as <token>. Keep the header name exactly as x-access-key and supply the token as the header value. If the header is missing or incorrect, treat the request as not properly authorized and check the token and header spelling before retrying. No other authorization scheme is described in the captured contract for this endpoint, so do not substitute a different header or credential format.

Path parameters field map: accountId and videoId

Both path parameters are required strings. The accountId is the integration ID of the connected YouTube channel, while videoId is the YouTube video ID. Substitute each value into its matching placeholder in the path. A common failure is swapping the two values or using a display name or URL in place of the actual IDs; verify that accountId refers to the connected channel and videoId refers to the specific video. Also verify that videoId satisfies the captured length constraint of 1 <= length before calling the endpoint. The worked example in the request sample shows the substitution pattern without changing the underlying contract.

Response body overview: 200, 404, and 502

The endpoint documents three JSON response statuses: 200, 404, and 502. A 200 response contains the full video details object. A 404 response and a 502 response each contain only the success and message fields in the captured contract. Your client should therefore check the status code first, then parse according to the matching shape. On a 200 response, read success, accountId, platform, and the nested video object. On a 404 or 502 response, read success and message and surface the message to the caller or log it for diagnosis. The captured source does not specify additional error semantics, retry behavior, or rate limits for these statuses, so do not invent them in client logic.

200 application/json field map

On success, the response body is application/json with success set as a boolean, accountId as a string, platform as the string youtube, and video as an object. Inside video, videoId, channelId, title, description, categoryId, and privacyStatus are strings; tags is an array of strings; and madeForKids and containsSyntheticMedia are booleans. The privacyStatus value is one of public, private, or unlisted. Use channelId to confirm which channel the video belongs to, categoryId for category handling, and the two boolean flags for kids and synthetic-media handling. Preserve the exact field names when mapping the response into your own models, and treat every listed field as required in the captured contract.

404 application/json field map

A 404 response body is application/json containing success as a boolean and message as a string. When you receive this status, read the message field for the returned explanation and do not attempt to read a video object, because the captured 404 shape does not include one. Check that the accountId and videoId values were correct and that the video is accessible through the selected connected channel before retrying. The captured contract does not define further 404 semantics, so avoid adding assumptions about the underlying cause.

502 application/json field map

A 502 response body is application/json containing success as a boolean and message as a string. When you receive this status, read the message field and do not attempt to read a video object, because the captured 502 shape does not include one. The captured contract does not specify what upstream condition produces a 502, nor does it define retry behavior, so record the status and message for diagnosis and follow your own service-level retry policy rather than assuming endpoint-defined retry rules. Keep the 502 handling distinct from the 404 handling so that not-found cases and upstream-failure cases are not conflated in logs or user-facing messages.

Path parameters
ParameterLocationTypeRequiredDescriptionConstraints
accountIdpathstringtrueIntegration ID of the connected YouTube channel.
videoIdpathstringtrueYouTube video ID.1 <= length

Captured contract; videoId length constraint preserved exactly.

200 response fields
FieldTypeRequiredDescription
successbooleantrue
accountIdstringtrue
platformstringtrueEnum: youtube
videoobjecttrue
video.videoIdstringtrue
video.channelIdstringtrue
video.titlestringtrue
video.descriptionstringtrue
video.tagsarray<string>true
video.categoryIdstringtrue
video.privacyStatusstringtrueEnum: public | private | unlisted
video.madeForKidsbooleantrue
video.containsSyntheticMediabooleantrue

Captured contract; platform enum and privacyStatus enum preserved exactly.

404 and 502 response fields
StatusFieldTypeRequired
404successbooleantrue
404messagestringtrue
502successbooleantrue
502messagestringtrue

Captured contract; no additional error semantics specified.

Get YouTube video details request
curl -X GET "{{API_BASE_URL}}/v1/youtube/accounts/{accountId}/videos/{videoId}" \
  -H "x-access-key: <token>"
200 response example
{
  "success": true,
  "accountId": "string",
  "platform": "youtube",
  "video": {
    "videoId": "string",
    "channelId": "string",
    "title": "string",
    "description": "string",
    "tags": [
      "string"
    ],
    "categoryId": "string",
    "privacyStatus": "public",
    "madeForKids": true,
    "containsSyntheticMedia": true
  }
}
404 and 502 response example
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
accountId#1accountIdstring__0Yesthe service integration ID of the connected YouTube channel.
videoId#2videoIdstring__0YesYouTube video ID.kind: schemaLength; value: 1 <= length
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.accountIdstring__2Yes
response#3response.platformstring__3Yeskind: ; value: "youtube"
response#3response.videoobject__4Yes
response#3response.video.videoIdstring__5Yes
response#3response.video.channelIdstring__6Yes
response#3response.video.titlestring__7Yes
response#3response.video.descriptionstring__8Yes
response#3response.video.tagsarray<string>__9Yes
response#3response.video.tags[]string__10
response#3response.video.categoryIdstring__11Yes
response#3response.video.privacyStatusstring__12Yeskind: ; value: "public" | "private" | "unlisted"
response#3response.video.madeForKidsboolean__13Yes
response#3response.video.containsSyntheticMediaboolean__14Yes
response#4responseobject__0
response#4response.successboolean__1Yes
response#4response.messagestring__2Yes