/

Browse the help center

Create campaign capping

Creates a new capping rule for the specified campaign, controlling how frequently events (impressions, clicks, or actions) occur within a time window.

Reference

POST https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/{campaignId}.do

Creates a new capping rule for the specified campaign, controlling how frequently events (impressions, clicks, or actions) occur within a time window. The capping type determines which event category is capped (e.g. CAMPAIGN_FREQUENCY for impressions, CAMPAIGN_CLICKS for clicks). The response JSON carries the new record, with its assigned id, under capping. Requires UPDATE permission on the campaign's advertiser, MANAGE_CAPPING_AND_LIMITATIONS enabled, and the permission of the capping type and subject.

Path Params

campaignId integer required

Numeric ID of the campaign to add the capping rule to

2001

Form Params

type string required

Type of the capping to create. Only campaign types are accepted: CAMPAIGN_REQUEST, CAMPAIGN_FREQUENCY, CAMPAIGN_CLICKS, CAMPAIGN_ACTIONS, CAMPAIGN_NO_CLICK, CAMPAIGN_DSP_FREQUENCY and CAMPAIGN_DSP_FREQUENCY_MONTH (period=1, periodType DAY or MONTH, flat=false), CAMPAIGN_DSP_RECENCY (amount=1, periodType MINUTE, period 1..60, flat=false). BANNER_*, PLACEMENT_* and ADVERTISER_* values are listed by the shared enum but rejected with 'Capping type is incompatible with entity'

CAMPAIGN_FREQUENCY

amount integer required

Maximum number of events allowed within the specified period

1000

period integer required

Length of the capping time window, expressed in units defined by periodType

24

periodType string required

Unit of the capping period. Allowed values: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR

HOUR

flat boolean required

When true, events are distributed evenly (flat) across the period instead of being served/counted as fast as possible

true

subject string

Entity used to identify unique users for capping. Optional; allowed values: USER_COOKIE, USER_SERVER_SIDE, USER_MIXED, IP, LES_IP

USER_COOKIE

Responses

200

Capping created: {success, capping:{id, type, amount, period, periodType, flat, subject, ...}}

400

Bad request — invalid or missing parameters

401

Authentication error

403

Forbidden — insufficient permissions

404

Not found — resource does not exist

Language

cURL Request

curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=CAMPAIGN_FREQUENCY' \
  --data-urlencode 'amount=1000' \
  --data-urlencode 'period=24' \
  --data-urlencode 'periodType=HOUR' \
  --data-urlencode 'flat=true' \
  --data-urlencode 'subject=USER_COOKIE'

Python Request

import requests

response = requests.request("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do", headers={"X-Api-Key": "YOUR_API_KEY"}, data={"type": "CAMPAIGN_FREQUENCY", "amount": "1000", "period": "24", "periodType": "HOUR", "flat": "true", "subject": "USER_COOKIE"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({"type":"CAMPAIGN_FREQUENCY","amount":"1000","period":"24","periodType":"HOUR","flat":"true","subject":"USER_COOKIE"}),
});

console.log(await response.json());

Java Request

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", HttpRequest.BodyPublishers.ofString("type=CAMPAIGN_FREQUENCY&amount=1000&period=24&periodType=HOUR&flat=true&subject=USER_COOKIE"))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C# Request

using var client = new HttpClient();

var request = new HttpRequestMessage(new HttpMethod("POST"), "https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");
request.Content = new FormUrlEncodedContent(new Dictionary<string, string> { ["type"] = "CAMPAIGN_FREQUENCY", ["amount"] = "1000", ["period"] = "24", ["periodType"] = "HOUR", ["flat"] = "true", ["subject"] = "USER_COOKIE" });

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Go Request

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do", strings.NewReader(`type=CAMPAIGN_FREQUENCY&amount=1000&period=24&periodType=HOUR&flat=true&subject=USER_COOKIE`))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

PHP Request

<?php
$ch = curl_init("https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: YOUR_API_KEY", "Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'type=CAMPAIGN_FREQUENCY&amount=1000&period=24&periodType=HOUR&flat=true&subject=USER_COOKIE');

echo curl_exec($ch);
curl_close($ch);

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/campaign/capping/2001.do")
request = Net::HTTP::Post.new(uri)
request['X-Api-Key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/x-www-form-urlencoded'
request.set_form_data('type' => "CAMPAIGN_FREQUENCY", 'amount' => "1000", 'period' => "24", 'periodType' => "HOUR", 'flat' => "true", 'subject' => "USER_COOKIE")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.body