📍
Video campaigns (aka brand video) require a special Taboola account.

Overview

Video campaigns allow you to run video advertising campaigns on the Taboola platform. This documentation focuses on managed campaigns.

Managed video campaigns

Managed campaigns are fully optimized by Taboola algorithms, with budget-based pacing and scheduling controls.

Business models:

CPM - Cost per mille (per 1,000 impressions)
CPCV - Cost per completed view
VCPM - Viewable cost per mille

Authentication

All video campaign management endpoints require authentication using OAuth 2.0. You must obtain an access token and include it in the Authorization header of each request:

Authorization: Bearer {access_token}

For detailed authentication instructions, see: Client Credentials Flow

Managing campaigns

Fetch operations

List video campaigns

Retrieve a list of video campaigns for your account.

GET /backstage/api/1.0/{account_id}/video-campaigns

Params:

Param	Type	Required	Description
`account_id`	string	Yes	Your account ID, as an alphabetic string. See: Get Account Details

{
  "results": [
    {
      "id": 12345678,
      "content_provider": 987654,
      "campaign_name": "Summer Video Campaign 2024",
      "business_model": "CPM",
      "deal_id": null,
      "status": "ACTIVE",
      "start_date": "2024-06-01",
      "end_date": "2024-08-31",
      "restrictions": [...],
      "total_spent": 2500.00,
      "auction_type": null,
      "cpm_floor": null,
      "daily_impressions_limit": null,
      "impressions_limit": null,
      "total_budget": 10000.0,
      "charge_rate": 5.50,
      "completed_views": 1500,
      "active": true
    }
  ],
  "totalCount": 1
}

🚧
The network account

The video-campaigns endpoint returns a list of video campaigns owned (created) by that account.

Because your network account is not used to create campaigns, it cannot be used with the network-campaigns endpoint.

However, you can fetch basic details for all campaigns across the network, using the video-campaigns/base endpoint.

Get a video campaign

Retrieve details for a specific video campaign.

GET /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}

{
  "id": 12345678,
  "content_provider": 987654,
  "campaign_name": "Summer Video Campaign 2024",
  "business_model": "CPM",
  "deal_id": null,
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "INCLUDE",
      "value": ["1", "2"],
      "restriction_name": "PLATFORM"
    }
  ],
  "total_spent": 2500.00,
  "auction_type": null,
  "cpm_floor": null,
  "daily_impressions_limit": null,
  "impressions_limit": null,
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Params:

Param	Type	Required	Description
`account_id`	string	Yes	Your account ID, as an alphabetic string
`campaign_id`	string	Yes	The campaign ID

Create operations

Create a managed video campaign

Create a new managed video campaign.

📘
POST
To create a video campaign, use the POST operation.

POST /backstage/api/1.0/{account_id}/video-campaigns/managed

{
  "campaign_name": "Product Launch Video Campaign",
  "business_model": "CPM",
  "start_date": "2024-07-01",
  "end_date": "2024-09-30",
  "total_budget": 15000.0,
  "charge_rate": 6.00,
  "pacing": "BALANCED",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "INCLUDE",
      "value": ["1"],
      "restriction_name": "PLATFORM"
    }
  ]
}

{
  "id": 87654321,
  "content_provider": 987654,
  "campaign_name": "Product Launch Video Campaign",
  "business_model": "CPM",
  "deal_id": null,
  "status": "PENDING_APPROVAL",
  "start_date": "2024-07-01",
  "end_date": "2024-09-30",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "INCLUDE",
      "value": ["1"],
      "restriction_name": "PLATFORM"
    }
  ],
  "total_spent": null,
  "auction_type": null,
  "cpm_floor": null,
  "daily_impressions_limit": null,
  "impressions_limit": null,
  "total_budget": 15000.0,
  "charge_rate": 6.00,
  "pacing": "BALANCED",
  "completed_views": 0,
  "active": true
}

Create a managed campaign (minimal fields)

Create a managed video campaign with only the required fields.

📘
Required fields
The restrictions array is required and must include at least one restriction with restriction_name of "COUNTRY".

POST /backstage/api/1.0/{account_id}/video-campaigns/managed

{
  "campaign_name": "Minimal Managed Campaign",
  "business_model": "CPM",
  "start_date": "2024-07-01",
  "charge_rate": 5.00,
  "total_budget": 5000.0,
  "pacing": "BALANCED",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    }
  ]
}

{
  "id": 87654321,
  "content_provider": 987654,
  "campaign_name": "Minimal Managed Campaign",
  "business_model": "CPM",
  "deal_id": null,
  "status": "PENDING_APPROVAL",
  "start_date": "2024-07-01",
  "end_date": null,
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    }
  ],
  "total_spent": null,
  "auction_type": null,
  "cpm_floor": null,
  "daily_impressions_limit": null,
  "impressions_limit": null,
  "total_budget": 5000.0,
  "charge_rate": 5.00,
  "pacing": "BALANCED",
  "completed_views": 0,
  "active": true
}

Duplicate a video campaign

Duplicate an existing video campaign to create a copy.

Duplicate a managed campaign

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}/duplicate

{
  "campaign_name": "Copy of Summer Video Campaign 2024"
}

{
  "id": 87654321,
  "content_provider": 987654,
  "campaign_name": "Copy of Summer Video Campaign 2024",
  "business_model": "CPM",
  "deal_id": null,
  "status": "PENDING_APPROVAL",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA"],
      "restriction_name": "COUNTRY"
    }
  ],
  "total_spent": null,
  "auction_type": null,
  "cpm_floor": null,
  "daily_impressions_limit": null,
  "impressions_limit": null,
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "pacing": "BALANCED",
  "completed_views": 0,
  "active": true
}

Params:

Param	Type	Required	Description
`account_id`	string	Yes	Your account ID, as an alphabetic string
`campaign_id`	string	Yes	The campaign ID to duplicate
`destination_account`	string	No	Destination account ID (optional)

Update operations

Update a managed video campaign

Update an existing managed video campaign. You can submit only the fields that need updating.

📘
POST
To update a managed video campaign, use the POST operation.

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}

{
  "campaign_name": "Updated Managed Campaign",
  "charge_rate": 7.00,
  "total_budget": 20000.0,
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA", "UK"],
      "restriction_name": "COUNTRY"
    }
  ]
}

👍
Partial updates supported
You only need to include the fields you want to change. All other fields will remain unchanged.

{
  "id": 12345678,
  "content_provider": 987654,
  "campaign_name": "Updated Managed Campaign",
  "business_model": "CPM",
  "deal_id": null,
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA", "UK"],
      "restriction_name": "COUNTRY"
    }
  ],
  "total_spent": 3500.00,
  "auction_type": null,
  "cpm_floor": null,
  "daily_impressions_limit": null,
  "impressions_limit": null,
  "total_budget": 20000.0,
  "charge_rate": 7.00,
  "pacing": "BALANCED",
  "completed_views": 1500,
  "active": true
}

Params:

Param	Type	Required	Description
`account_id`	string	Yes	Your account ID, as an alphabetic string
`campaign_id`	string	Yes	The campaign ID

Pause a video campaign

Pause a video campaign by updating its status.

📘
Managed campaigns only
This example uses the managed campaign endpoint.

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}

{
  "status": "PAUSED"
}

{
  "id": 12345678,
  "content_provider": 987654,
  "campaign_name": "Summer Video Campaign 2024",
  "business_model": "CPM",
  "deal_id": null,
  "status": "PAUSED",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    }
  ],
  "total_spent": 2500.00,
  "auction_type": null,
  "cpm_floor": null,
  "daily_impressions_limit": null,
  "impressions_limit": null,
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "pacing": "BALANCED",
  "completed_views": 1500,
  "active": true
}

Params:

Param	Type	Required	Description
`account_id`	string	Yes	Your account ID, as an alphabetic string
`campaign_id`	string	Yes	The campaign ID

Resume a video campaign

Resume a paused video campaign by updating its status.

📘
Managed campaigns only
This example uses the managed campaign endpoint.

POST /backstage/api/1.0/{account_id}/video-campaigns/managed/{campaign_id}

{
  "status": "ACTIVE"
}

{
  "id": 12345678,
  "content_provider": 987654,
  "campaign_name": "Summer Video Campaign 2024",
  "business_model": "CPM",
  "deal_id": null,
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    }
  ],
  "total_spent": 2500.00,
  "auction_type": null,
  "cpm_floor": null,
  "daily_impressions_limit": null,
  "impressions_limit": null,
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "pacing": "BALANCED",
  "completed_views": 1500,
  "active": true
}

Campaign status values

Status	Description
`PENDING_APPROVAL`	Campaign awaiting approval
`ACTIVE`	Campaign is running
`PAUSED`	Campaign is paused
`COMPLETED`	Campaign has finished
`REJECTED`	Campaign was rejected
`DELETED`	Campaign was deleted

Delete operations

Delete a video campaign

Delete a video campaign.

DELETE /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}

{
  "id": 12345678,
  "status": "DELETED"
}

Params:

Param	Type	Required	Description
`account_id`	string	Yes	Your account ID, as an alphabetic string
`campaign_id`	string	Yes	The campaign ID

Campaign fields

Common fields

All video campaigns include these base fields:

Field	Type	Required	Description
`id`	long	No	Campaign ID (auto-generated)
`content_provider`	long	No	Content provider ID
`campaign_name`	string	Yes	Campaign name
`business_model`	string	Yes	Campaign business model
`deal_id`	string	No	External deal identifier
`status`	string	No	Campaign status
`start_date`	string	Yes	Campaign start date (YYYY-MM-DD)
`end_date`	string	No	Campaign end date (YYYY-MM-DD)
`restrictions`	array	Yes	Targeting restrictions array
`total_spent`	number	No	Total amount spent
`auction_type`	string	No	Auction type
`cpm_floor`	number	No	CPM floor value
`daily_impressions_limit`	number	No	Daily impression limit
`impressions_limit`	number	No	Total impression limit
`active`	boolean	No	Whether campaign is active

Managed campaign fields

Managed campaigns include these additional fields:

Field	Type	Required	Description
`total_budget`	double	Yes	Total campaign budget
`charge_rate`	double	Yes	Campaign rate (CPM/CPCV)
`pacing`	string	Yes	Campaign pacing (BALANCED/ACCELERATED)
`daily_cap`	double	No	Daily budget cap (optional)
`activity_schedule`	object	No	Campaign scheduling rules
`completed_views`	integer	No	Number of completed video views

Error responses

Validation errors

{
  "error": "VALIDATION_ERROR",
  "message": "Campaign name is required",
  "details": {
    "field": "campaign_name",
    "code": "REQUIRED_FIELD"
  }
}

```json 400 Bad Request
{
  "http_status": 400,
  "message": "campaign.video.server.error.missing.field.pacing",
  "offending_field": "pacing",
  "message_code": "campaign.video.server.error.missing.field.pacing",
  "template_parameters": []
}

Not found errors

{
  "error": "NOT_FOUND",
  "message": "Campaign not found",
  "details": {
    "campaignId": "12345"
  }
}

Rate limit errors

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "details": {
    "retryAfter": 60
  }
}

What's next?

Now that you understand video campaign management, explore these related topics:

Targeting - Configure targeting options for your video campaigns
Video campaign creatives - Manage video campaign creatives
Reports - Access performance analytics and reporting data
Conversion rules - Set up conversion tracking for your campaigns

These are the same as sponsored content campaigns
Custom audiences - Create and manage custom audience segments

These are the same as sponsored content campaigns

Video campaigns

Overview

Managed video campaigns

Authentication

Managing campaigns

Fetch operations

List video campaigns

The network account

Get a video campaign

Create operations

Create a managed video campaign

`POST`

Create a managed campaign (minimal fields)

Required fields

Duplicate a video campaign

Duplicate a managed campaign

Update operations

Update a managed video campaign

`POST`

Partial updates supported

Pause a video campaign

Managed campaigns only

Resume a video campaign

Managed campaigns only

Campaign status values

Delete operations

Delete a video campaign

Campaign fields

Common fields

Managed campaign fields

Error responses

Validation errors

Not found errors

Rate limit errors

What's next?