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.
| Parameter | Location | Type | Required | Description | Constraints |
|---|---|---|---|---|---|
| accountId | path | string | true | Integration ID of the connected YouTube channel. | |
| videoId | path | string | true | YouTube video ID. | 1 <= length |
Captured contract; videoId length constraint preserved exactly.
| Field | Type | Required | Description |
|---|---|---|---|
| success | boolean | true | |
| accountId | string | true | |
| platform | string | true | Enum: youtube |
| video | object | true | |
| video.videoId | string | true | |
| video.channelId | string | true | |
| video.title | string | true | |
| video.description | string | true | |
| video.tags | array<string> | true | |
| video.categoryId | string | true | |
| video.privacyStatus | string | true | Enum: public | private | unlisted |
| video.madeForKids | boolean | true | |
| video.containsSyntheticMedia | boolean | true |
Captured contract; platform enum and privacyStatus enum preserved exactly.
| Status | Field | Type | Required |
|---|---|---|---|
| 404 | success | boolean | true |
| 404 | message | string | true |
| 502 | success | boolean | true |
| 502 | message | string | true |
Captured contract; no additional error semantics specified.
curl -X GET "{{API_BASE_URL}}/v1/youtube/accounts/{accountId}/videos/{videoId}" \
-H "x-access-key: <token>"{
"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
}
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | Yes | the service integration ID of the connected YouTube channel. | |
| videoId#2 | videoId | string | __0 | Yes | YouTube video ID. | kind: schemaLength; value: 1 <= length |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.accountId | string | __2 | Yes | ||
| response#3 | response.platform | string | __3 | Yes | kind: ; value: "youtube" | |
| response#3 | response.video | object | __4 | Yes | ||
| response#3 | response.video.videoId | string | __5 | Yes | ||
| response#3 | response.video.channelId | string | __6 | Yes | ||
| response#3 | response.video.title | string | __7 | Yes | ||
| response#3 | response.video.description | string | __8 | Yes | ||
| response#3 | response.video.tags | array<string> | __9 | Yes | ||
| response#3 | response.video.tags[] | string | __10 | |||
| response#3 | response.video.categoryId | string | __11 | Yes | ||
| response#3 | response.video.privacyStatus | string | __12 | Yes | kind: ; value: "public" | "private" | "unlisted" | |
| response#3 | response.video.madeForKids | boolean | __13 | Yes | ||
| response#3 | response.video.containsSyntheticMedia | boolean | __14 | Yes | ||
| response#4 | response | object | __0 | |||
| response#4 | response.success | boolean | __1 | Yes | ||
| response#4 | response.message | string | __2 | Yes |