Campaign Groups Overview

A campaign group is a container that holds one or more campaigns under a shared configuration. Campaign groups manage budget, spending limits, conversion attribution, and other settings across their linked campaigns.

A campaign can belong to exactly 1 campaign group.

What you can do via the API

Action	Endpoint
Create a campaign group	`POST /campaigns_group`
Fetch a campaign group	`GET /campaigns_group/{id}`
List campaign groups	`GET /campaigns_group`
Update a campaign group	`POST /campaigns_group/{id}`
Delete a campaign group	`DELETE /campaigns_group/{id}`
Activate or deactivate in bulk	`POST /entities/activations`

All endpoint paths are prefixed with /backstage/api/1.0/{account_id}, except the bulk-activation endpoint which is /backstage/api/1.0/entities/activations.

Campaign group fields

The following fields appear on a campaign group resource. Required fields must be sent on create. Read-only fields appear on fetch but cannot be set. Final fields are set once at create time and become read-only afterward.

Field	Modifier	Type	Description
`id`	Read-only	Long	Unique ID of the campaign group.
`name`	Required	String	Name of the campaign group.
`status`	Read-only	String	One of: `RUNNING`, `PAUSED`, `PENDING_START_DATE`, `DEPLETED_MONTHLY`, `DEPLETED`, `EXPIRED`, `TERMINATED`, `FROZEN`.
`marketing_objective`	Required, Final	Enum	One of: `BRAND_AWARENESS`, `LEADS_GENERATION`, `ONLINE_PURCHASES`, `DRIVE_WEBSITE_TRAFFIC`, `MOBILE_APP_INSTALL`.
`kpi`	Optional	Enum	Success metric used by the campaign group. One of: `ROAS`, `CPA`, `CTR`, `CPI`, `CPL`, `CPC`, `CPQV`, `CPM`.
`kpi_data`	Optional	Object	Success metric threshold values. Contains `kpi_goal_value` and `kpi_threshold_value`; both must be positive when provided.
`start_date`	Optional, Final, Default: now	Date (`yyyy-MM-dd`)	Start date in the account's timezone. Must be today or later.
`start_date_in_utc`	Read-only	Date (`yyyy-MM-dd HH:mm:ss`)	Resolved start date in UTC.
`end_date`	Optional, Default: `9999-12-31` (no end date)	Date (`yyyy-MM-dd`)	End date in the account's timezone. Must be after `start_date`.
`end_date_in_utc`	Read-only	Date (`yyyy-MM-dd HH:mm:ss`)	Resolved end date in UTC.
`spending_limit_model`	Required	Enum	One of: `NONE`, `MONTHLY`, `ENTIRE`.
`spending_limit`	Required	Double	Max amount to be spent (within the model).
`daily_cap`	Optional, Default: 0.0	Double	The daily upper budget for the campaign group. Applies when `daily_ad_delivery_model = STRICT`. Must be lower than `spending_limit`. `0.0` means "unlimited".
`daily_ad_delivery_model`	Optional	Enum	One of: `BALANCED`, `ACCELERATED`, `STRICT`.
`is_active`	Default: `true`	Boolean	If `false`, the group is paused and `status` becomes `PAUSED`.
`account_id`	Optional, Final	String	The account's alphabetic ID. Required when creating from a network-level path. Otherwise, the value is taken from the path.
`numeric_account_id`	Optional, Final	Long	The account's numeric ID.
`language`	Default: `EN`	String	2-letter language code (ISO 639-1).
`conversion_rules`	Default: `{rules: []}`	Object	See conversion rules below. When omitted, defaults to the account's conversion rules that are marked Include in total conversions.

🚧
Field validation
Submitting field values outside their allowed range or type returns 400 Bad Request.

Conversion rule object

The conversion rules applied to the campaign group.

{
  "conversion_rules": {
    "rules": [
      {
        "id": 14,
        "display_name": "test-rule1",
        "status": "ACTIVE",
        "include_in_total_conversions": true
      }
    ]
  }
}

Field	Modifier	Type	Description
`id`	Required	Long	Numeric ID of an existing conversion rule.
`display_name`	Read-only	String	Conversion rule name.
`status`	Read-only	String	Conversion rule status.
`include_in_total_conversions`	Read-only	Boolean	Whether the rule contributes to total conversions.

Associating a campaign with a campaign group

The link between a campaign and its campaign group is set on the campaign object via the campaign_group_id field.

Field	Modifier	Type	Description
`campaign_group_id`	Optional, Final	Long	Numeric ID of the campaign group this campaign belongs to. Set once at creation. Cannot be reassigned.

📘
Shared-budget groups
When a campaign is linked to a shared-budget group, you can omit spending_limit and spending_limit_model from the campaign request.

Create a campaign linked to a campaign group

POST /backstage/api/1.0/{account_id}/campaigns/ HTTP/1.1
Host: backstage.taboola.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "My Campaign",
  "branding_text": "My Brand",
  "bid_strategy": "FIXED",
  "cpc": 0.25,
  "marketing_objective": "DRIVE_WEBSITE_TRAFFIC",
  "campaign_group_id": 12345
}

Fetch a campaign

When you fetch a campaign, campaign_group_id appears in the response.

{
  "id": "67890",
  "name": "My Campaign",
  "campaign_group_id": 12345,
  ...
}

📘
Backward compatibility
The legacy campaign_groups object is deprecated. For backward compatibility, either field can be passed on create, and both fields are returned on fetch. If both fields are sent on the same request, campaign_group_id takes precedence. New integrations should use campaign_group_id.