Send early ad break notifications

Google Dynamic Ad Insertion (DAI) supports livestreams at a high concurrency level. Early Ad Break Notifications (EABN) are requests for Google DAI to schedule an upcoming ad break or immediately start ad decisions, optimizing both ad fill rate and load time.

To begin early ad break notifications for full service, pod serving, or server guided ad insertion, use the AdBreaks resource. This resource can create and manage ad breaks for all livestreams you create through Google Ad Manager UI, or Google Ad Manager SOAP API LiveStreamEventService.

This page covers how to schedule an ad break as an early ad break notification.

Note: If you're using the earlier version of the Early Ad Break Notification API, upgrade to the AdBreaks resource for parity and advanced features, such as scheduling an ad break and querying ad break states.

Prerequisites

To create or manage the ad breaks, you need a livestream system generated asset key or custom asset key. You can also find these keys on the livestream details page. See Set up a livestream for DAI using the Google Ad Manager UI.

Schedule an ad break

You can schedule an ad break while your stream viewership increases. For each livestream event, schedule one ad break individually up to six hours in advance using the Create service method. Include your expected start time and ad break ID. DAI begins ad decisions close to the scheduled time. For immediate ad break decisions, omit the ad break expected start time.

To make Google DAI start ad decisions immediately, you can omit the ad break's expected start time when calling Create.

The following example schedules an ad break for a livestream event of type Linear to start on March 6th, 2025 at 4:00 PM in Coordinated Universal Time (UTC):

cURL

curl 'https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreamEventsByAssetKey/ASSET_KEY/adBreaks' \
  -H 'authorization: Bearer ACCESS_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"adBreakId":"mid-roll-1","assetKey":"ASSET_KEY","duration":"30s","expectedStartTime":"2025-03-06T16:00:00Z"}'

Node.js

fetch("https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreamEventsByAssetKey/ASSET_KEY/adBreaks", {
    "headers": {
      "authorization":
        "Bearer ACCESS_TOKEN",
        "Content-Type": "application/json",
    },
  "body": JSON.stringify({
    "adBreakId": "mid-roll-1",
    "duration": "30s",
    "expectedStartTime": "2025-03-06T16:00:00Z"
  }),
  "method": "POST"
});

If successful, you see the following JSON response:

{
  "name": "networks/.../liveStreamEventsByAssetKey/.../adBreaks/mid-roll-1",
  "adBreakId": "mid-roll-1",
  "assetKey": "...",
  "expectedStartTime": "2025-03-06T16:00:00Z",
  "duration": "30s",
  "breakState": "SCHEDULED"
}

Tip: Check the livestream event's DynamicAdInsertionType property. If it is POD_SERVING_REDIRECT or POD_SERVING_MANIFEST, we recommend passing a custom ad break ID provided by your stream manifest manipulator. Otherwise, the API will generate a UUID string for the ad break ID.

To query ad breaks, use the List method. To inspect an ad break's details, use the Get method.

The following example lists all ad breaks for a livestream event:

cURL

curl 'https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreamEventsByAssetKey/ASSET_KEY/adBreaks' \
  -H 'authorization: Bearer ACCESS_TOKEN'

Node.js

fetch(
  "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreamEventsByAssetKey/ASSET_KEY/adBreaks",
  {
    "headers": {
      "authorization": "Bearer ACCESS_TOKEN",
    },
    "method": "GET"
  }
);

If successful, you see the following JSON response:

{
  "adBreaks": [
    {
      "name": "networks/.../liveStreamEventsByAssetKey/.../adBreaks/mid-roll-1",
      "adBreakId": "mid-roll-1",
      "assetKey": "...",
      "expectedStartTime": "2025-03-06T16:00:00Z",
      "duration": "30s",
      "breakState": "DECISIONED",
      "breakSequence": "1"
    }
  ]
}

If you want to reschedule the current ad break to sooner, use the Patch method to change the expected start time. If you want to cancel the current ad break, use the Delete method before its state is COMPLETED.

To create another ad break, wait until the current ad break's state is COMPLETED.