The Google Dynamic Ad Insertion (DAI) Ad Break API lets you create and manage the timing and ad targeting data of ad breaks in your livestreams. This guide covers using the DAI Ad Break API to create, update, and delete an ad break for a Google DAI livestream event. ## Prerequisites To use the DAI Ad Break API, you need the following: - A Google Cloud project with the `admanagervideo.googleapis.com` service enabled. For more information, see [Create a Cloud project](https://developers.google.com/workspace/guides/create-project#project). - A Google Ad Manager network with a Google DAI livestream event. For more information, see [Set up a livestream for DAI](https://support.google.com/admanager/answer/7294289). ### Set up API access To enable the API, complete the following steps: 1. Create a service account. For more information, see [Create a service account](https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount). 2. Add the service account to your Google Ad Manager network. For more information, see [Add a service account user for API access](https://support.google.com/admanager/answer/6078734). 3. Provide the service account email address and your Google Ad Manager network code to your Google account manager. 4. Enable the Google Ad Manager Video API in your Google Cloud project. For more information, see [Enable "APIs \& Services" for your app](https://support.google.com/cloud/answer/13461325). ### Authenticate with OAuth2 To authorize your API requests, do the following steps: 1. [Generate the access token](https://docs.cloud.google.com/iam/docs/create-short-lived-credentials-direct#create-access) with the `https://www.googleapis.com/auth/video-ads` scope. 2. In each request, include the access token to the API as an `Authorization` HTTP header `Bearer` value. For more information, see [Call Google APIs](https://developers.google.com/identity/protocols/oauth2/service-account#callinganapi). The following example generates an OAuth token with the DAI Ad Break API scope: gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads' If successful, you see the following access token: ya29.c.c0ASRK0GYUYU0... ## Make the first request To retrieve ad breaks for a livestream event, use the `GET` method to list all `AdBreak` entities by the event's system-generated [asset key](https://developers.google.com/ad-manager/api/reference/latest/LiveStreamEventService.LiveStreamEvent#assetkey), or your [custom asset key](https://developers.google.com/ad-manager/api/reference/latest/LiveStreamEventService.LiveStreamEvent#customassetkey). The DAI Ad Break API only returns `AdBreak` entities that are created through the API, excluding ad breaks created from the manifest, pod segment request, or pod manifest request. The following example request lists the `AdBreak` entities by an `assetKey` value: curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer OAUTH_TOKEN" If successful, you see the following JSON response: { "adBreaks": [] } As you create additional `AdBreak` entities through the API and request the list, you see the following JSON response: { "adBreaks": [ { "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854", "expectedDuration": "30s", "expectedStartTime": "2025-06-03T15:00:00Z", "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==", "breakParams": { "adTagParams": [ { "key": "ptpln", "value": "podtemplate" }, { "key": "cust_params", "value": "param1=value1¶m2=value2" } ] }, "breakState": "BREAK_STATE_SCHEDULED" }, { "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c", "breakSequence": "1", "expectedDuration": "30s", "expectedStartTime": "2025-06-03T14:30:00Z", "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==", "breakParams": { "adTagParams": [ { "key": "ptpln", "value": "podtemplate" }, { "key": "cust_params", "value": "param1=value1¶m2=value2" } ] }, "breakState": "BREAK_STATE_COMPLETE" }, ... ], "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC" } ### Create an AdBreak entity To inform Google DAI of an upcoming ad break for a livestream event, use the `POST` method. > [!IMPORTANT] > **Important:** You can only have one `AdBreak` entity in `BREAK_STATE_SCHEDULED` or `BREAK_STATE_DECISIONED` state at a time for each livestream event. - To create a new `AdBreak` entity, you must wait for the previous one to transition to the `BREAK_STATE_COMPLETE` state. - Alternatively, you can delete the pending `AdBreak` entity in order to create a new one. - To create more than one `AdBreak` entity for a single livestream event, contact your account manager for advanced configuration. The following example request creates an ad break expected to start on June 3, 2025, at 15:00:00 UTC: curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer OAUTH_TOKEN" \ -d '{ "expectedDuration": "30s", "expectedStartTime": "2025-06-03T15:00:00Z", "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==", "breakParams": { "adTagParams": [ { "key": "ptpln", "value": "podtemplate" }, { "key": "cust_params", "value": "param1=value1¶m2=value2" } ] } }' If successful, you see the following JSON response: { "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854", "expectedDuration": "30s", "expectedStartTime": "2025-06-03T15:00:00Z", "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==", "breakParams": { "adTagParams": [ { "key": "ptpln", "value": "podtemplate" }, { "key": "cust_params", "value": "param1=value1¶m2=value2" } ] }, "breakState": "BREAK_STATE_SCHEDULED" } The result contains the ad break ID required for retrieving, modifying, or deleting the ad break. In the example response, the created ad break ID is `bcc402a6-9880-4b8b-8e4a-a8cd3688f854`. ### Retrieve an AdBreak entity Use the `GET` method to retrieve the details of a specific `AdBreak` entity, including ad break state and timing metadata. curl -X GET \ 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer OAUTH_TOKEN' If successful, you see the following JSON response: { "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854", "expectedDuration": "30s", "expectedStartTime": "2025-06-03T15:10:00Z", "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==", "breakParams": { "adTagParams": [ { "key": "ptpln", "value": "podtemplate" }, { "key": "cust_params", "value": "param1=value1¶m2=value2" } ] }, "breakState": "BREAK_STATE_SCHEDULED" } ### Update an AdBreak entity To modify an upcoming ad break before the ad decision begins, use the `PATCH` method: curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer OAUTH_TOKEN' \ -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}' If successful, you see the following JSON response: { "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854", "expectedDuration": "30s", "expectedStartTime": "2025-06-03T15:10:00Z", "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==", "breakParams": { "adTagParams": [ { "key": "ptpln", "value": "podtemplate" }, { "key": "cust_params", "value": "param1=value1¶m2=value2" } ] }, "breakState": "BREAK_STATE_SCHEDULED" } ### Delete an AdBreak entity Use the `DELETE` method to cancel the ad decision for an ad break created through the API before the ad break begins to serve. > [!CAUTION] > **Caution:** Deleting an ad break in the `BREAK_STATE_DECISIONED` state can prevent ad servers from delivering ads, which can negatively impact ad server budgeting and frequency capping functionalities. For more information, see [Understand the ad break lifecycle](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/ad-break#understand_the_ad_break_lifecycle). The following example request deletes an ad break: curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \ -H 'Authorization: Bearer OAUTH_TOKEN' If successful, you see the `HTTP/1.1 200 OK` response. ### Learn advanced ad break features After creating and managing ad breaks, explore these features of the DAI Ad Break API: - To override ad tag parameters for an ad break, or integrate with third-party ad systems, see [Use ad break parameters](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/ad-break/use-ad-break-params). - To prevent ad-related playback errors, see [Manage ad break and segment durations](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/ad-break/manage-ad-break-segment).