The Dynamic Ad Insertion (DAI) Stream Activity Monitor (SAM) API lets you
retrieve diagnostic logs and delivery results for your livestream and
video-on-demand (VOD) sessions.

This guide covers how to configure authentication, retrieve a top-level
`DaiSession` resource, and request the resources identified in the
session's fields.

## Prerequisites

To use the SAM API, you need the following:

- Access to the Google Ad Manager API. For more information, see [Getting started](https://developers.google.com/ad-manager/api/beta/getting-started.md.txt).
- A configured DAI livestream or VOD stream. For more information, see [Set up a livestream for DAI](https://support.google.com/admanager/answer/7294289) and [Create a content source for video on demand](https://support.google.com/admanager/answer/7064112).
- A DAI session ID or debug key from a stream creation request. For details, see [Locate a DAI session ID or debug key](https://support.google.com/admanager/answer/7257678).

## Request a `DaiSession` resource

To inspect a DAI session, send an HTTP `GET` request to the
[`networks.daiSessions.get`](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.daiSessions/get.md.txt) endpoint with a DAI
session ID or a DAI stream debug key.

### Retrieve a `DaiSession` resource by ID

When you register a stream session using IMA DAI SDK, Full-service DAI API,
or Pod serving DAI API, Google DAI returns a DAI session ID.

The following example retrieves a `DaiSession` resource using the session ID:

```bash
curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"
```

Replace the following:

- `NETWORK_CODE`: your Google Ad Manager network code
- `SESSION_ID`: the DAI session ID returned when creating the stream session
- `OAUTH_TOKEN`: your OAuth 2.0 access token

### Use a debug key for DAI session

When you register a stream session, you can assign a custom debug key by using
the `dai-sam-id` parameter or the `sam_id` parameter in Pod serving VOD
requests. You can pass this debug key directly in the `DaiSession` resource
path.

The following example retrieves a `DaiSession` resource using the debug key:

```bash
curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
    -H "Authorization: Bearer OAUTH_TOKEN"
```

Replace `DEBUG_KEY` with a custom debug
key specified in your stream creation request.

Both requests return a `DaiSession` JSON response containing the session
context, ad selections, decisioned ad pods, ad breaks, and diagnostic findings.
The output is similar to the following:

```json
{
  "name": "networks/21775744923/daiSessions/9587e2c1-d745-4bf1-9f6a-e9092127cb48:ATL",
  "creationContext": {
    "streamCreateRequest": {
      "requestTime": "2026-10-16T19:59:57.365124Z",
      "latency": "0.045s",
      "url": "/ssai/event/c-rArva4ShKVIAkNfy6HUQ/streams",
      "userAgent": "Mozilla/5.0",
      "responseCode": 201
    },
    "linearInfo": {
      "liveStream": "networks/21775744923/liveStreams/20000016294786",
      "assetKey": "c-rArva4ShKVIAkNfy6HUQ",
      "prefetchEnabled": false,
      "podTrimmingEnabled": true,
      "podTrimTolerance": "2s",
      "eventStartTime": "2020-06-09T20:00:00Z",
      "eventEndTime": "2037-01-01T08:00:00Z"
    },
    "debugKey": "my-custom-debug-key-001",
    "contentTitle": "IMA sample HLS live stream",
    "stitchingType": "STITCHED",
    "reportingType": "CLIENT",
    "interstitialEnabled": false
  },
  "slate": {
    "idType": "CREATIVE_ID",
    "idValue": "138544327419",
    "adSystem": "GDFP",
    "duration": "10s"
  },
  "adSelections": {
    "2021043961286562353": {
      "type": "VAST",
      "adRequest": {
        "adRequestKey": "2021043961286562353",
        "adTag": "https://pubads.g.doubleclick.net/gampad/live/ads?iu=/21775744923/external/vmap_ads_for_dai&cust_params=sample_ar%3Dstreammidonly&output=xml_vast4&pmxd=30000",
        "httpRequest": {
          "requestTime": "2026-10-16T19:59:57.177283526Z",
          "latency": "0.138s",
          "url": "https://pubads.g.doubleclick.net/gampad/live/ads?iu=/21775744923/external/vmap_ads_for_dai&cust_params=sample_ar%3Dstreammidonly&output=xml_vast4&pmxd=30000",
          "responseCode": 200,
          "responseBody": "<VAST version=\"4.0\"><Ad id=\"5937252921\" sequence=\"1\"><InLine><AdSystem>GDFP</AdSystem><AdTitle>External - Pod Midroll 1</AdTitle><Creatives><Creative id=\"138383221557\" sequence=\"1\"><Linear><Duration>00:00:10</Duration></Linear></Creative></Creatives></InLine></Ad></VAST>"
        },
        "childRequests": []
      }
    }
  },
  "adPods": {
    "9204525715521575580": {
      "requestedBreakType": "MIDROLL",
      "adRequestKey": "2021043961286562353",
      "prefetchStage": "DISABLED",
      "adBreakId": "-3821178632466845617",
      "label": "3196133",
      "creatives": {
        "6086226973783046639": {
          "idType": "GOOGLE_VIDEO_REGISTRY_ID",
          "idValue": "tVFdo4-fFVE",
          "adSystem": "GDFP",
          "duration": "10.010s",
          "podSequence": 1,
          "adBuffet": false,
          "vastInfos": [
            {
              "adSystem": "GDFP",
              "adTitle": "External - Pod Midroll 1",
              "creativeId": "138383221557"
            }
          ]
        }
      }
    }
  },
  "adBreaks": {
    "-3821178632466845617": {
      "podKeys": [
        "9204525715521575580"
      ],
      "adBreakId": "-3821178632466845617",
      "breakType": "MIDROLL",
      "breakSequence": "3196133",
      "servedAdsDuration": "30.999999999s",
      "executedBreakDuration": "30.999999999s",
      "linear": {
        "breakStartTime": "2026-10-16T20:22:28.130329Z",
        "expectedBreakDuration": "31s",
        "slateDuration": "0s",
        "underlyingDuration": "0s"
      },
      "trackingPings": {
        "3641994172850159057": {
          "originalTrackingEventId": "google_4445276280058090123",
          "request": {
            "requestTime": "2026-10-16T20:22:29.393993Z",
            "latency": "0.030s",
            "url": "https://dai.google.com/view/p/service/linear/impression/stream/1dccd632-5028-45be-a68a-6c90645cd237:ATL/network/21775744923/event/xDte1UxoSxmtRrB6lqHdmg/media/7083951761/stream_ad_id/EfzeSEQzFPU",
            "responseCode": 200
          }
        }
      }
    }
  },
  "findings": [
    {
      "severity": "INFO",
      "description": "Minimum slate inserted into underfilled ad break.",
      "slateFinding": {
        "type": "SLATE_STATUS_MINIMUM_INSERTED"
      }
    },
    {
      "severity": "INFO",
      "description": "Ad break was decisioned, but not served during playback.",
      "adBreakFinding": {
        "type": "UNSERVED_BREAK",
        "breakKey": "-3821178632466845617"
      }
    }
  ],
  "sessionDuration": "31.453022s"
}
```

## Request related resources

After you identify a session, you can query specific session fields in the
`DaiSession` resource, navigate entity keys from session findings, or make
follow-up requests to related resources in the Ad Manager API.

### Filter session fields with field masks

A full `DaiSession` response includes raw VAST and VMAP XML bodies and all
historical break events. To reduce payload size and fetch only the session
fields you need, pass a read mask in the `fields` query parameter or the
`X-Goog-FieldMask` HTTP header. For details, see
[Field Masks](https://developers.google.com/ad-manager/api/beta/field-masks.md.txt).

To check whether a session encountered errors, request only the session
creation context and diagnostic findings:

```bash
curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID?fields=name,creationContext,findings" \
    -H "Authorization: Bearer OAUTH_TOKEN"
```

To retrieve only the `adBreaks` and `adPods` fields without downloading the raw
XML ad responses in the `adSelections` field, use the `X-Goog-FieldMask` header:

```bash
curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN" \
    -H "X-Goog-FieldMask: name,adBreaks,adPods"
```

### Inspect session findings

Each entry in the `findings` list includes a typed finding object with a key
that points to the specific entity in the `DaiSession` resource. The following
table shows how to resolve finding keys to session fields:

| Finding key path | Target location in `DaiSession` |
|---|---|
| `adBreakFinding.breakKey` | `adBreaks[breakKey]` |
| `adRequestFinding.adSelectionKey`, `adRequestFinding.adRequestKey` | `adSelections[adSelectionKey].adRequest` and nested `childRequests[]` |
| `creativeFinding.creativeKey` | Match `creativeKey` across entries in `adPods[podKey].creatives[creativeKey]` |
| `podFinding.podKey` | `adPods[podKey]` |
| `slateFinding` | `slate` |
| `trackingFinding.trackingPingKey` | Match `trackingPingKey` across entries in `adBreaks[breakKey].trackingPings[trackingPingKey]` |

To trace relationships across collections, do the following:

1. Start from an entry in the `adBreaks` array.
2. Read the `podKeys` list to locate the corresponding entries in the `adPods` array.
3. Use the `adPod.adRequestKey` field on the pod to find the matching `AdRequest.adRequestKey` in the `adSelections` array.
4. Inspect the originating HTTP request and VAST response in the matching `adRequest` object or its nested `childRequests` array.

### Request the livestream and content resources

A `DaiSession` resource contains resource names that link to the
[livestream](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.liveStreams/get.md.txt) and [content](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.content/get.md.txt)
resources in the Google Ad Manager API on the `admanager.googleapis.com`
endpoint. To verify the stream configuration and content metadata, you can make
HTTP `GET` requests to these resources:

- **`LiveStream`** resource: Use the value of the `creationContext.linearInfo.liveStream` field to call the [`networks.liveStreams.get` method](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.liveStreams/get.md.txt).
- **VOD `Content` resource** : Use the value of the `creationContext.vodInfo.content` field to call the [`networks.content.get` method](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.content/get.md.txt).

The following example retrieves the linked `LiveStream` resource referenced in
the `creationContext.linearInfo.liveStream` field:

```bash
curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreams/LIVE_STREAM_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"
```

Replace `LIVE_STREAM_ID` with the
livestream ID in your `DaiSession` resource.

The output is similar to the following:

```json
{
  "name": "networks/21775744923/liveStreams/20000016294786",
  "displayName": "IMA sample HLS live stream",
  "status": "ACTIVE",
  "createTime": "2020-06-09T20:00:07Z",
  "updateTime": "2026-08-18T15:37:05Z",
  "startTime": "2020-06-09T20:00:00Z",
  "endTime": "2037-01-01T08:00:00Z",
  "endTimeUnlimited": true,
  "contentUrls": [
    "https://contentsim.sandbox.google.com/content/590f95c5-c3ee-4a56-a10c-0cc660e91faa/linear/multivariant.m3u8"
  ],
  "adTags": [
    "https://pubads.g.doubleclick.net/gampad/live/ads?sz=640x480&output=xml_vast3&iu=/21775744923/external/vmap_ads_for_dai&env=vp&impl=s&gdfp_req=1&unviewed_position_start=1&ad_rule=0&cust_params=sample_ar%3Dstreammidonly&lseco=%%ASSET_KEY%%"
  ],
  "assetKey": "c-rArva4ShKVIAkNfy6HUQ",
  "slate": "networks/21775744923/slates/138544327419",
  "enableDaiAuthenticationKeys": false,
  "adBreakFillType": "SLATE",
  "underfillAdBreakFillType": "SLATE",
  "adHolidayDuration": "0s",
  "enableMaxFillerDuration": false,
  "enableDurationlessAdBreaks": false,
  "hlsSettings": {
    "playlistType": "LIVE",
    "masterPlaylistSettings": {
      "refreshType": "AUTOMATIC"
    }
  },
  "allowlistedIpsEnabled": false,
  "dynamicAdInsertionType": "LINEAR",
  "relativePlaylistDeliveryEnabled": false,
  "streamingFormat": "HLS",
  "prefetchEnabled": false,
  "forcedCueInEnabled": false,
  "shortSegmentDroppingEnabled": false,
  "adBreakMarkupTypesEnabled": false,
  "earlyBreakNotificationMultiBreakSchedulingEnabled": false,
  "dvrWindowDuration": "60s"
}
```