LiveBroadcasts: cuepoint

Inserts a cuepoint into a live broadcast. The cuepoint might trigger an ad break.

Note: This method replaces the liveCuepoints.insert method, which required requests to be authorized by an account associated with a YouTube Content Owner. This method does not have the same authorization requirement.

Request

HTTP request

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

Authorization

This request requires authorization with at least one of the following scopes (read more about authentication and authorization).

Scope
`https://www.googleapis.com/auth/youtube`
`https://www.googleapis.com/auth/youtube.force-ssl`
`https://www.googleapis.com/auth/youtubepartner`

Parameters

The following table lists the parameters that this query supports. All of the parameters listed are query parameters.

Parameters
Required parameters
`id`	`string` The `id` parameter identifies the broadcast into which the cuepoint is being inserted. The broadcast must be actively streaming when inserting the cuepoint.
Optional parameters
`onBehalfOfContentOwner`	`string` This parameter can only be used in a properly authorized request. Note: This parameter is intended exclusively for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide different authentication credentials for each separate channel. The account that the user authenticates with must be linked to the specified YouTube content owner. The `onBehalfOfContentOwner` parameter indicates that the request's authorization credentials identify a YouTube user who is acting on behalf of the YouTube Content Owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels.
`onBehalfOfContentOwnerChannel`	`string` This parameter can only be used in a properly authorized request. Note: This parameter is intended exclusively for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and perform actions on behalf of the channel specified in the parameter value, without having to provide authentication credentials for each separate channel. The `onBehalfOfContentOwnerChannel` parameter specifies the YouTube channel ID of the channel associated with the broadcast into which the cuepoint is being inserted. This parameter is required when a request specifies a value for the `onBehalfOfContentOwner` parameter, and it can only be used in conjunction with that parameter. The following requirements also apply: The request must be authorized with a user account linked to the content owner that the `onBehalfOfContentOwner` parameter specifies. The channel that the `onBehalfOfContentOwnerChannel` parameter value specifies must be linked to the content owner that the `onBehalfOfContentOwner` parameter specifies.

Request body

Provide a cuepoint resource in the request body. The following JSON structure shows the format of a cuepoint resource:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }

In the request body, the cueType field is required and must be set to cueTypeAd. You can also set values for these properties:

durationSecs
insertionOffsetTimeMs (must not be set if walltimeMs is set)
walltimeMs (must not be set if insertionOffsetTimeMs is set)

Properties

The following table defines the properties that appear in this resource:

Properties
`id`	`string` A value that YouTube assigns to uniquely identify the cuepoint. Note that this value is different from the required `id` parameter, which identifies the broadcast. This value can be omitted when sending a request to insert a cuepoint. The value will be populated in the API response.
`insertionOffsetTimeMs`	`long` The property value identifies a time offset, in milliseconds, when the cuepoint should be inserted. The value is measured from the beginning of the monitor stream, and its default value is `0`, which indicates that the cuepoint should be inserted as soon as possible. You should not specify a value for this parameter if your broadcast does not have a monitor stream. Though measured in milliseconds, the value is actually an approximation, and YouTube will insert the cuepoint as closely as possible to that time. Non-zero values for this field are supported only if the broadcast stream is delayed. If your broadcast stream is not delayed, then `0` is the only valid value. See the Getting started guide for more details. Note: If your broadcast had a testing phase, the offset is measured from the time that the testing phase began. The API returns an error if a request tries to insert a cuepoint that specifies a value for this property and for the `walltimeMs` property.
`walltimeMs`	`integer` The property value specifies the wall clock time at which the cuepoint should be inserted. The value is an integer that represents an epoch timestamp (in milliseconds). The API returns an error if a request tries to insert a cuepoint that specifies a value for this property and for the `insertionOffsetTimeMs` property.
`durationSecs`	`unsigned integer` The cuepoint's duration, in seconds. The value must be a positive integer. The default value is `30`.
`cueType`	`string` The cuepoint's type. The property value must be set to `cueTypeAd`.

Response

If successful, this method returns the inserted cuepoint resource in the response body.

Errors

The following table identifies error messages that the API could return in response to a call to this method. The error message documentation Identifies all of the errors that the Live Streaming API can return.

Error type	Error detail	Description
`insufficientPermissions (403)`	`insufficientLivePermissions`	The request is not authorized to insert a cuepoint in the live broadcast.
`insufficientPermissions (403)`	`liveStreamingNotEnabled`	The user that authorized the request is not enabled to stream live video on YouTube. The user can find more information at https://support.google.com/youtube/answer/2474026 and https://www.youtube.com/features.
`rateLimitExceeded (403)`	`userRequestsExceedRateLimit`	The user has sent too many requests in a given timeframe.
`required (400)`	`idRequired`	The required `id` parameter must identify the broadcast in which you want to insert a cuepoint.
`required (400)`	`cueTypeRequired`	The required `cueType` field must be specified in the API request body.
`notFound (404)`	`liveBroadcastNotFound`	The broadcast specified by the `id` parameter does not exist.
`invalidValue (400)`	`conflictingTimeFields`	Only one of `insertionOffsetTimeMs` and `walltimeMs` may be specified. Setting both values causes an error. If you do not set either value, YouTube will use the default `insertionOffsetTimeMs` time (`0`), which means that the cuepoint will be inserted as soon as possible.
`invalidValue (400)`	`invalidInsertionOffsetTimeMs`	The `cuepoint` resource specified an invalid value for the `insertionOffsetTimeMs` property. The value must be `0` or a positive integer.
`invalidValue (400)`	`invalidWalltimeMs`	The `cuepoint` resource specified an invalid value for the `walltimeMs` property. The value must be an integer that represents an epoch timestamp (in milliseconds).
`backendError (5xx)`	`serviceUnavailable`	The service is unavailable. Try your request again after a few minutes.

Try it!

Use the APIs Explorer to call this API and see the API request and response.