---
updatedAt: 2026-09-24T11:53:05.000Z
agentTools:
projectIndex: https://developers.taboola.com/backstage-api/llms.txt
---
# Create a Custom Audience Rule
> 🚧 display\_name
>
> `display_name` must be *unique* across all Custom Audience Rules, for a given account.
>
> If you create a new Custom Audience Rule with an existing `display_name`, the API returns **Error 500**.
> 📘 Exclude From ALL Campaigns
>
> To exclude a custom audience *by default*, set `exclude_from_campaigns` to *true*. (Applies to new *and* existing campaigns.)
>
> You can *override* this behavior for a given *campaign* by updating its [Custom Audience Targeting](https://developers.taboola.com/backstage-api/reference/update-custom-audience-targeting) to target this audience.
> 🚧 Network account
>
> You can invoke this endpoint using the [network account](https://developers.taboola.com/backstage-api/docs/network-accounts).\
> The audience created will be visible to *all* sub-accounts in the network.
>
> ***
>
> For more detail, see: [Network Accounts](https://developers.taboola.com/backstage-api/docs/network-accounts).
> 📘 Custom Audiences
>
> To create and manage [pixel-based](https://developers.taboola.com/backstage-api/docs/taboola-pixel-overview) custom audiences, use **Backstage API** (*this topic*).
>
> To create and manage *CRM-based* custom audiences, use **Backstage UI**.
>
> To *target* either of the above audiences in a campaign, use **Backstage API** ([Get Custom Audience Targeting](red:get-custom-audience-targeting) and [Update Custom Audience Targeting](https://developers.taboola.com/backstage-api/reference/update-custom-audience-targeting)).
```json Sample Request
{
"display_name": "Add to cart",
"look_back_window": null,
"category": "ADD_TO_CART",
"status": "ACTIVE",
"type": "BASIC",
"event_name": "page_view",
"condition": {
"property": "URL",
"predicate": "CONTAINS",
"value": "test.com",
"children": []
},
"effects": [
{
"type": "REVENUE",
"data": "15"
}
],
"include_in_total_conversions": true,
"exclude_from_campaigns": false,
"description": null,
"last_modified_at": null
}
```
```json Sample Response (200 OK)
{
"id": 75,
"display_name": "Add to cart",
"look_back_window": null,
"category": "ADD_TO_CART",
"status": "ACTIVE",
"type": "BASIC",
"event_name": "page_view",
"condition": {
"property": "URL",
"predicate": "CONTAINS",
"value": "test.com",
"children": []
},
"exclude_from_campaigns": false,
"description": null,
"advertiser_id": "demo-advertiser",
"last_modified_by": "peter.pan@taboola.com",
"last_modified_at": null,
"audience_size": 0
}
```
> 📘 audience\_size
>
> The *Customer Audience Rule* returned in the response contains an `audience_size` field.
```json Sample Request (Insufficient Fields)
{
"look_back_window": null,
"category": "ADD_TO_CART",
"status": "ACTIVE",
"type": "BASIC",
"event_name": "page_view",
"condition": {
"property": "URL",
"predicate": "CONTAINS",
"value": "test.com",
"children": []
},
"effects": [
{
"type": "REVENUE",
"data": "15"
}
],
"include_in_total_conversions": true,
"exclude_from_campaigns": false,
"description": null,
"last_modified_at": null
}
```
```json Sample Response (Insufficient Fields)
{
"http_status": 400,
"message": "Missing required field 'displayName'",
"offending_field": "display_name"
}
```
## Rate limit
> 🚧 Rate limit
>
> **Tier 2.** Shares one budget with updating a custom audience rule. Reading custom audience rules, and all conversion rule endpoints, draw on separate budgets.
>
> See [Rate limits](https://developers.taboola.com/backstage-api/reference/rate-limits) for the request allowance each tier carries.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "backstage-api",
"version": "1.0"
},
"servers": [
{
"url": "https://backstage.taboola.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "https://backstage.taboola.com/backstage/oauth/token",
"scopes": {}
},
"password": {
"tokenUrl": "https://backstage.taboola.com/backstage/oauth/token",
"scopes": {}
}
}
}
}
},
"security": [
{
"sec0": []
}
],
"x-readme": {
"headers": [],
"explorer-enabled": false,
"proxy-enabled": false
},
"paths": {
"/backstage/api/1.0/{account_id}/universal_pixel/custom_audience_rule/": {
"post": {
"summary": "Create a Custom Audience Rule",
"description": "",
"operationId": "create-a-custom-audience-rule",
"parameters": [
{
"name": "account_id",
"in": "path",
"description": "An *alphabetic* ID. See [Get Account Details](https://developers.taboola.com/backstage-api/reference/get-account-details).",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"RAW_BODY"
],
"properties": {
"RAW_BODY": {
"type": "string",
"description": "A JSON object representing the new Custom Audience Rule.
(See below for an example.)",
"default": "{ \"display_name\": \"Add to cart - Rev 11\", \"look_back_window\": null, \"category\": \"ADD_TO_CART\", \"status\": \"ACTIVE\", \"type\": \"BASIC\", \"event_name\": \"page_view\", \"condition\": { \"property\": \"URL\", \"predicate\": \"CONTAINS\", \"value\": \"test.com\", \"children\": [] }, \"effects\": [ { \"type\": \"REVENUE\", \"data\": \"15\" } ], \"include_in_total_conversions\": true, \"exclude_from_campaigns\": false, \"description\": null, \"last_modified_at\": null }",
"format": "json"
}
}
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"id\": 75,\n \"display_name\": \"Add to cart\",\n \"look_back_window\": null,\n \"category\": \"ADD_TO_CART\",\n \"status\": \"ACTIVE\",\n \"type\": \"BASIC\",\n \"event_name\": \"page_view\",\n \"condition\": {\n \"property\": \"URL\",\n \"predicate\": \"CONTAINS\",\n \"value\": \"test.com\",\n \"children\": []\n },\n \"exclude_from_campaigns\": false,\n \"description\": null,\n \"advertiser_id\": \"demo-advertiser\",\n \"last_modified_by\": \"peter.pan@taboola.com\",\n \"last_modified_at\": null,\n \"audience_size\": 0\n}"
}
},
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 75,
"default": 0
},
"display_name": {
"type": "string",
"example": "Add to cart"
},
"look_back_window": {},
"category": {
"type": "string",
"example": "ADD_TO_CART"
},
"status": {
"type": "string",
"example": "ACTIVE"
},
"type": {
"type": "string",
"example": "BASIC"
},
"event_name": {
"type": "string",
"example": "page_view"
},
"condition": {
"type": "object",
"properties": {
"property": {
"type": "string",
"example": "URL"
},
"predicate": {
"type": "string",
"example": "CONTAINS"
},
"value": {
"type": "string",
"example": "test.com"
},
"children": {
"type": "array"
}
}
},
"exclude_from_campaigns": {
"type": "boolean",
"example": false,
"default": true
},
"description": {},
"advertiser_id": {
"type": "string",
"example": "demo-advertiser"
},
"last_modified_by": {
"type": "string",
"example": "peter.pan@taboola.com"
},
"last_modified_at": {},
"audience_size": {
"type": "integer",
"example": 0,
"default": 0
}
}
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"http_status\": 400,\n \"message\": \"Missing required field\",\n \"offending_field\": \"display name\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"http_status": {
"type": "integer",
"example": 400,
"default": 0
},
"message": {
"type": "string",
"example": "Missing required field"
},
"offending_field": {
"type": "string",
"example": "display name"
}
}
}
}
}
}
},
"deprecated": false
}
}
}
}
```