Use DAI Ad Break API

DAI Ad Break API lets you create, manage the timing and ad targeting data of ad breaks in your livestreams.

This guide covers using DAI Ad Break API to create, update and delete an ad break for a Google Dynamic Ads Insertion (DAI) livestream event.

Prerequisites

To use 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.
  • A Google Ad Manager network with a Google DAI livestream event. For more information, see Set up a livestream for DAI.

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.
  2. Add the service account to your Google Ad Manager network. For more information, see Add a service account user for API access.
  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.

Authenticate with OAuth2

To authorize your API requests, do the following steps:

  1. Generate the access token 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.

The following example generates an OAuth token with the DAI Ad Break API's 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, or your custom asset key.

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==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "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==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "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.

  • 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 3rd, 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==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

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==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

The result contains the ad break IDrequired 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==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "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==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "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.

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: