---
title: Ads Cue Points
url: https://docs.kaltura.com/docs/embeddable-kaltura-products/kaltura-player/ads-cue-points
---

## Kaltura Ad Cue Points API

Ad cue points define when and how advertisements play during video content.  
They support VAST and VPAID protocols for pre-roll, mid-roll, post-roll,  
and overlay ad insertion.

**Base URL:** `$KALTURA_SERVICE_URL` (e.g., `https://www.kaltura.com/api_v3`)  
**Auth:** KS via `ks` parameter (admin KS with `disableentitlement` for full access)  
**Format:** `format=1` for JSON responses  
**Service:** `cuepoint_cuepoint` (shared with all cue point types)  
**objectType:** `KalturaAdCuePoint`  
**Prerequisite:** [Cue Points Hub](/docs/embeddable-kaltura-products/kaltura-player/cue-points) for base cue point concepts and shared CRUD

<!-- Sections: 1.When to Use | 2.Prerequisites | 3.Ad Types | 4.Fields (in addition to base) | 5.Protocol Types | 6.Ad Placement | 7.Create a Mid-Roll Ad | 8.Create an Overlay Ad | 9.Protocol Immutability | 10.Player Ad Plugin Integration | 11.Searching Ad Cue Points | 12.Error Handling | 13.Best Practices | 14.Related Guides -->


## 1. When to Use

- **Video monetization** — Insert pre-roll, mid-roll, and post-roll advertisements into video content to generate ad revenue from your video library.  
- **Publisher ad management** — Define ad break positions on the video timeline and link them to VAST or VPAID ad feeds served by your ad network.  
- **Overlay promotions** — Display non-linear banner overlays at specific moments during playback without interrupting the video content.  
- **Sponsored content integration** — Place sponsor messages at precise points in educational, entertainment, or event recordings.  
- **Dynamic ad scheduling** — Programmatically manage ad cue points across large content libraries, enabling bulk ad insertion and per-entry ad customization.


## 2. Prerequisites

- **KS (Kaltura Session):** Admin KS (type=2) with `disableentitlement` for creating and managing ad cue points.  
- **Cue Points plugin:** The `cuePoint` and `adCuePoint` server plugins must be enabled on the account.  
- **Ad server:** A VAST or VPAID-compliant ad server providing XML ad feeds at accessible URLs.  
- **Player ad plugin:** To trigger ads during playback, enable the `kalturaCuepoints` and `bumper` plugins in the player configuration.  
- **Session management:** See [Session Guide](/docs/getting-started/authentication/ks-overview) for KS generation and privilege scoping.


## 3. Ad Types

| Value | Name | Description |
|-------|------|-------------|
| 1 | VIDEO | Linear ad — pauses video content |
| 2 | OVERLAY | Non-linear ad — displays over video content |


## 4. Fields (in addition to base)

| Field | Type | Description |
|-------|------|-------------|
| `protocolType` | int | Ad protocol (insert-only, **immutable** after creation) |
| `sourceUrl` | string | URL to VAST/VPAID XML feed |
| `adType` | int | 1=VIDEO (linear), 2=OVERLAY (non-linear) |
| `title` | string | Ad title (max 250 chars) |
| `endTime` | int | End time in milliseconds |
| `duration` | int | Duration in milliseconds |


## 5. Protocol Types

| Value | Name | Description |
|-------|------|-------------|
| 0 | CUSTOM | Custom ad protocol |
| 1 | VAST | VAST 1.0 |
| 2 | VAST_2_0 | VAST 2.0 |
| 3 | VPAID | VPAID |


## 6. Ad Placement

| Placement | startTime | Description |
|-----------|-----------|-------------|
| Pre-roll | `0` | Plays before video content |
| Mid-roll | `N` (in ms) | Plays at position N in the video |
| Post-roll | `duration` | Plays after video content |
| Overlay | any | Non-linear overlay with `adType=2` and `startTime`/`endTime` defining the visible window |


## 7. Create a Mid-Roll Ad

```bash
curl -X POST "$KALTURA_SERVICE_URL/service/cuepoint_cuepoint/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "cuePoint[objectType]=KalturaAdCuePoint" \
  -d "cuePoint[entryId]=$KALTURA_ENTRY_ID" \
  -d "cuePoint[startTime]=120000" \
  -d "cuePoint[protocolType]=2" \
  -d "cuePoint[sourceUrl]=https://example.com/vast/midroll.xml" \
  -d "cuePoint[adType]=1" \
  -d "cuePoint[title]=Sponsor message"
```


## 8. Create an Overlay Ad

```bash
curl -X POST "$KALTURA_SERVICE_URL/service/cuepoint_cuepoint/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "cuePoint[objectType]=KalturaAdCuePoint" \
  -d "cuePoint[entryId]=$KALTURA_ENTRY_ID" \
  -d "cuePoint[startTime]=30000" \
  -d "cuePoint[endTime]=45000" \
  -d "cuePoint[protocolType]=1" \
  -d "cuePoint[sourceUrl]=https://example.com/vast/overlay.xml" \
  -d "cuePoint[adType]=2" \
  -d "cuePoint[title]=Banner overlay"
```

Overlay ads use `adType=2` with both `startTime` and `endTime` to define the visible window.


## 9. Protocol Immutability

`protocolType` cannot be changed after creation — attempting to update it returns `PROPERTY_VALIDATION_NOT_UPDATABLE`. Plan the protocol type before creating ad cue points.


## 10. Player Ad Plugin Integration

The Player v7 `bumper` plugin handles ad playback based on ad cue points. Configure the player with the `kalturaCuepoints` core plugin to load ad cue point data:

```javascript
plugins: {
  kalturaCuepoints: {},
  bumper: {}
}
```

The bumper plugin reads ad cue points and triggers VAST/VPAID requests at the specified `startTime`.


## 11. Searching Ad Cue Points

Ad cue point titles are indexed in eSearch via `KalturaESearchCuePointItem` with `fieldName=name`. See [Cue Points Hub — eSearch Integration](/docs/embeddable-kaltura-products/kaltura-player/cue-points) for query examples.


## 12. Error Handling

| Error | Cause | Fix |
|-------|-------|-----|
| `PROPERTY_VALIDATION_CANNOT_BE_NULL` | List without identifying filter | Include `entryIdEqual`, `entryIdIn`, `idEqual`, or `idIn` |
| `INVALID_CUE_POINT_ID` | Cue point not found or already deleted | Verify ID exists and status is not DELETED |
| `PROPERTY_VALIDATION_NOT_UPDATABLE` | Updating `protocolType` on ad cue point | `protocolType` is immutable after creation |


## 13. Best Practices

- **Times are in milliseconds.** A cue point at 2 minutes = `startTime=120000`.
- **Ad `protocolType` is set once.** Plan the protocol type before creating ad cue points — it cannot be changed.
- **Use `adType=1` for linear (video) ads** that pause content, `adType=2` for overlay (non-linear) ads.
- **Set `endTime` for overlay ads** to define the visible window. Linear ads play their full duration.
- **Use VAST 2.0 (protocolType=2)** for the most widely supported ad format.


## 14. Related Guides

- **[Cue Points Hub](/docs/embeddable-kaltura-products/kaltura-player/cue-points)** — Base cue point concepts, shared CRUD, eSearch integration, bulk operations
- **[Player Embed Guide](/docs/embeddable-kaltura-products/kaltura-player/player-embed-overview)** — Player v7 setup, ad plugin configuration
- **[Analytics Reports API](/docs/rich-media-cms-apis/analytics/analytics-overview)** — Ad engagement analytics