Overview

This guide provides a complete end-to-end workflow for working with motion ads using the Backstage API. It covers the entire lifecycle from creation to management, using only current, non-deprecated endpoints.

End-to-end workflow

1. Create motion ads

Use the Bulk Create Items endpoint to create motion ads across multiple campaigns in a single request.

Request

PUT /backstage/api/1.0/{account_id}/items/bulk

{
   "campaign_ids": [
      "campaign_id_1",
      "campaign_id_2"
   ],
   "items": [
      {
         "title": "Your video ad title",
         "url": "https://example.com/landing-page",
         "creative_type": "PERFORMANCE_VIDEO",
         "performance_video_data": {
            "video_url": "https://example.com/video.mp4",
            "fallback_url": "https://example.com/fallback.jpg"
         }
      }
   ]
}

Response

{
    "results": [
        {
            "id": "item_id_1",
            "campaign_id": "campaign_id_1",
            "type": "ITEM",
            "url": "https://example.com/landing-page",
            "title": "Your video ad title",
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "creative_type": "PERFORMANCE_VIDEO",
            "performance_video_data": {
                "video_url": "http://c3.taboola.com/libtrc/static/video/...",
                "fallback_url": "http://cdn.taboola.com/libtrc/static/thumbnails/...",
                "gif_url": "http://c3.taboola.com/libtrc/static/gif/..."
            }
        }
    ]
}

📘
Motion ads requirements

Video files: Must be in MP4 format

Fallback images: Must be in JPG or PNG format

URLs: Both video and fallback image URLs must be publicly accessible

Mixed content: You can mix static ads and motion ads in the same request

2. Retrieve motion ads

Use the Get All Campaign Items endpoint to fetch all items, including motion ads, for a campaign.

Request

GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/

Response

{
    "results": [
        {
            "id": "item_id_1",
            "campaign_id": "campaign_id_1",
            "type": "ITEM",
            "url": "https://example.com/landing-page",
            "title": "Your video ad title",
            "approval_state": "APPROVED",
            "is_active": true,
            "status": "RUNNING",
            "creative_type": "PERFORMANCE_VIDEO",
            "performance_video_data": {
                "video_url": "http://c3.taboola.com/libtrc/static/video/...",
                "fallback_url": "http://cdn.taboola.com/libtrc/static/thumbnails/...",
                "gif_url": "http://c3.taboola.com/libtrc/static/gif/..."
            }
        }
    ]
}

📘
Unified response
This endpoint returns both static ads and motion ads with their respective fields. Motion ads include the creative_type and performance_video_data fields.

3. Get specific motion ad details

Use the Get a Campaign Item endpoint to retrieve details for a specific motion ad.

Request

GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

Response

{
    "id": "item_id_1",
    "campaign_id": "campaign_id_1",
    "type": "ITEM",
    "url": "https://example.com/landing-page",
    "title": "Your video ad title",
    "approval_state": "APPROVED",
    "is_active": true,
    "status": "RUNNING",
    "creative_type": "PERFORMANCE_VIDEO",
    "performance_video_data": {
        "video_url": "http://c3.taboola.com/libtrc/static/video/...",
        "fallback_url": "http://cdn.taboola.com/libtrc/static/thumbnails/...",
        "gif_url": "http://c3.taboola.com/libtrc/static/gif/..."
    }
}

4. Update motion ads

Single motion ad update

Use the Update a Video Item endpoint to update a single motion ad.

PUT /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/performance-video/items/{item_id}

Multiple items update

Use the Bulk Update Items endpoint to update multiple items across campaigns.

POST /backstage/api/1.0/{account_id}/items/bulk

📘
Update flexibility

Use the single item endpoint for individual motion ad updates

Use the bulk update endpoint for multiple items or mixed ad types

5. Delete motion ads

Use the Delete a Campaign Item endpoint to delete motion ads.

Request

DELETE /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

Response

{
    "message": "Item deleted successfully"
}

📘
Unified deletion
This endpoint works for both static ads and motion ads. No special endpoint needed for motion ads.

6. Monitor performance

Use the Top Campaign Content Report to monitor performance of both static ads and motion ads.

Request

GET /backstage/api/1.0/{account_id}/reports/top-campaign-content

Response

{
    "results": [
        {
            "item_id": "item_id_1",
            "item_title": "Your video ad title",
            "creative_type": "PERFORMANCE_VIDEO",
            "impressions": 10000,
            "clicks": 500,
            "ctr": 0.05
        }
    ]
}

📘
Performance monitoring
The report includes both static ads and motion ads with their respective performance metrics.

Recommended workflow summary

Create: Use Bulk Create Items for initial creation
Retrieve: Use Get All Campaign Items to list all items
Details: Use Get a Campaign Item for specific item details
Update: Use Update a Video Item for single updates or Bulk Update Items for multiple
Delete: Use Delete a Campaign Item for removal
Monitor: Use Top Campaign Content Report for performance tracking

Key benefits

Unified endpoints: Most endpoints work with both static ads and motion ads
Bulk operations: Create and update multiple items efficiently
Mixed content: Combine static ads and motion ads in the same campaigns
Consistent API: Same patterns across all operations
Performance tracking: Comprehensive reporting for all ad types

📘
Best practices

Always provide both video and fallback image URLs for motion ads

Use bulk operations when working with multiple items

Monitor approval status after creation

Check performance reports regularly for optimization opportunities