Banner Campaign Performance Forecasts

curl --request POST \
  --url https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dailyBudget": 123,
  "dateRange": {
    "startDate": "2023-12-25",
    "endDate": "2023-12-25"
  },
  "targetRoas": 123,
  "slots": [
    {
      "id": "<string>",
      "bidAmount": 500000000
    }
  ],
  "triggers": [
    {
      "value": "<string>"
    }
  ],
  "targets": [],
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  },
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "user_segment",
        "segmentId": "<string>",
        "multiplier": 0.5
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  }
}
'

import requests

url = "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner"

payload = {
    "dailyBudget": 123,
    "dateRange": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25"
    },
    "targetRoas": 123,
    "slots": [
        {
            "id": "<string>",
            "bidAmount": 500000000
        }
    ],
    "triggers": [{ "value": "<string>" }],
    "targets": [],
    "targetingFilters": {
        "isActive": True,
        "targetingFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    },
    "multiplierConfig": {
        "isActive": True,
        "multipliers": [
            {
                "type": "user_segment",
                "segmentId": "<string>",
                "multiplier": 0.5
            }
        ]
    },
    "exclusionFilters": {
        "isActive": True,
        "exclusionFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dailyBudget: 123,
    dateRange: {startDate: '2023-12-25', endDate: '2023-12-25'},
    targetRoas: 123,
    slots: [{id: '<string>', bidAmount: 500000000}],
    triggers: [{value: '<string>'}],
    targets: [],
    targetingFilters: {
      isActive: true,
      targetingFilters: [{type: 'user_segment', segmentId: '<string>'}]
    },
    multiplierConfig: {
      isActive: true,
      multipliers: [{type: 'user_segment', segmentId: '<string>', multiplier: 0.5}]
    },
    exclusionFilters: {
      isActive: true,
      exclusionFilters: [{type: 'user_segment', segmentId: '<string>'}]
    }
  })
};

fetch('https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dailyBudget' => 123,
    'dateRange' => [
        'startDate' => '2023-12-25',
        'endDate' => '2023-12-25'
    ],
    'targetRoas' => 123,
    'slots' => [
        [
                'id' => '<string>',
                'bidAmount' => 500000000
        ]
    ],
    'triggers' => [
        [
                'value' => '<string>'
        ]
    ],
    'targets' => [
        
    ],
    'targetingFilters' => [
        'isActive' => true,
        'targetingFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ],
    'multiplierConfig' => [
        'isActive' => true,
        'multipliers' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>',
                                'multiplier' => 0.5
                ]
        ]
    ],
    'exclusionFilters' => [
        'isActive' => true,
        'exclusionFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner"

	payload := strings.NewReader("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"slots\": [\n    {\n      \"id\": \"<string>\",\n      \"bidAmount\": 500000000\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"slots\": [\n    {\n      \"id\": \"<string>\",\n      \"bidAmount\": 500000000\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"slots\": [\n    {\n      \"id\": \"<string>\",\n      \"bidAmount\": 500000000\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "forecasts": {
    "impressions": {
      "forecastValue": 150000,
      "forecastIntervalMin": 142000,
      "forecastIntervalMax": 158000
    },
    "clicks": {
      "forecastValue": 12500,
      "forecastIntervalMin": 11800,
      "forecastIntervalMax": 13200
    },
    "purchases": {
      "forecastValue": 875,
      "forecastIntervalMin": 820,
      "forecastIntervalMax": 930
    },
    "sales": {
      "forecastValue": 52500,
      "forecastIntervalMin": 49000,
      "forecastIntervalMax": 56000
    },
    "adSpend": {
      "forecastValue": 10500,
      "forecastIntervalMin": 10000,
      "forecastIntervalMax": 11000
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Forecasting Service

Banner Campaign Performance Forecasts

Get performance forecasts with confidence intervals for banner campaigns.

Slot ids: each slots[].id is the marketplace slot external id (auction-facing), not the internal slot UUID.

Campaign types:

autobidding: provide slots without bidAmount.
manual: every slot must include bidAmount > 0.

Target restrictions: only impressions, clicks, and ad_spend may be requested in targets.

Constraints:

Date range cannot exceed 31 days.

POST

public

toptimize

forecasting

campaigns

banner

Banner Campaign Performance Forecasts

curl --request POST \
  --url https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dailyBudget": 123,
  "dateRange": {
    "startDate": "2023-12-25",
    "endDate": "2023-12-25"
  },
  "targetRoas": 123,
  "slots": [
    {
      "id": "<string>",
      "bidAmount": 500000000
    }
  ],
  "triggers": [
    {
      "value": "<string>"
    }
  ],
  "targets": [],
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  },
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "user_segment",
        "segmentId": "<string>",
        "multiplier": 0.5
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  }
}
'

import requests

url = "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner"

payload = {
    "dailyBudget": 123,
    "dateRange": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25"
    },
    "targetRoas": 123,
    "slots": [
        {
            "id": "<string>",
            "bidAmount": 500000000
        }
    ],
    "triggers": [{ "value": "<string>" }],
    "targets": [],
    "targetingFilters": {
        "isActive": True,
        "targetingFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    },
    "multiplierConfig": {
        "isActive": True,
        "multipliers": [
            {
                "type": "user_segment",
                "segmentId": "<string>",
                "multiplier": 0.5
            }
        ]
    },
    "exclusionFilters": {
        "isActive": True,
        "exclusionFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dailyBudget: 123,
    dateRange: {startDate: '2023-12-25', endDate: '2023-12-25'},
    targetRoas: 123,
    slots: [{id: '<string>', bidAmount: 500000000}],
    triggers: [{value: '<string>'}],
    targets: [],
    targetingFilters: {
      isActive: true,
      targetingFilters: [{type: 'user_segment', segmentId: '<string>'}]
    },
    multiplierConfig: {
      isActive: true,
      multipliers: [{type: 'user_segment', segmentId: '<string>', multiplier: 0.5}]
    },
    exclusionFilters: {
      isActive: true,
      exclusionFilters: [{type: 'user_segment', segmentId: '<string>'}]
    }
  })
};

fetch('https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dailyBudget' => 123,
    'dateRange' => [
        'startDate' => '2023-12-25',
        'endDate' => '2023-12-25'
    ],
    'targetRoas' => 123,
    'slots' => [
        [
                'id' => '<string>',
                'bidAmount' => 500000000
        ]
    ],
    'triggers' => [
        [
                'value' => '<string>'
        ]
    ],
    'targets' => [
        
    ],
    'targetingFilters' => [
        'isActive' => true,
        'targetingFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ],
    'multiplierConfig' => [
        'isActive' => true,
        'multipliers' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>',
                                'multiplier' => 0.5
                ]
        ]
    ],
    'exclusionFilters' => [
        'isActive' => true,
        'exclusionFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner"

	payload := strings.NewReader("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"slots\": [\n    {\n      \"id\": \"<string>\",\n      \"bidAmount\": 500000000\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"slots\": [\n    {\n      \"id\": \"<string>\",\n      \"bidAmount\": 500000000\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/banner")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"slots\": [\n    {\n      \"id\": \"<string>\",\n      \"bidAmount\": 500000000\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "forecasts": {
    "impressions": {
      "forecastValue": 150000,
      "forecastIntervalMin": 142000,
      "forecastIntervalMax": 158000
    },
    "clicks": {
      "forecastValue": 12500,
      "forecastIntervalMin": 11800,
      "forecastIntervalMax": 13200
    },
    "purchases": {
      "forecastValue": 875,
      "forecastIntervalMin": 820,
      "forecastIntervalMax": 930
    },
    "sales": {
      "forecastValue": 52500,
      "forecastIntervalMin": 49000,
      "forecastIntervalMax": 56000
    },
    "adSpend": {
      "forecastValue": 10500,
      "forecastIntervalMin": 10000,
      "forecastIntervalMax": 11000
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Autorisations

Authorization

string

header

requis

A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key.

Corps

application/json

dailyBudget

number

requis

Daily budget for the campaign

dateRange

PublicDateRange · object

requis

Campaign date range

Show child attributes

targetRoas

number

requis

Target Return on Ad Spend

campaignType

enum<string>

requis

Campaign type (required)

Options disponibles:

autobidding,

manual

slots

PublicSlotRequest · object[]

requis

List of banner slots (required). Each id is the slot external id.

Required array length: 1 - 100 elements

Show child attributes

triggers

PublicTriggerRequest · object[]

List of campaign triggers (optional, defaults to empty list)

Show child attributes

targets

enum<string>[] | null

Optional list of target variables to forecast. If not provided, all targets will be forecasted.

Options disponibles:

ad_spend,

clicks,

impressions,

purchases,

sales

targetingFilters

PublicCampaignTargetingFilters · object | null

Optional audience targeting, in the same shape as campaign creation. When active, the forecast covers only users in these segments. Segment IDs are the marketplace's external segment IDs.

Show child attributes

multiplierConfig

PublicCampaignMultiplierConfig · object | null

Optional audience bid multipliers, in the same shape as campaign creation. Segment IDs are the marketplace's external segment IDs.

Show child attributes

exclusionFilters

PublicCampaignExclusionFilters · object | null

Optional audience exclusion, in the same shape as campaign creation. When active, the forecast leaves out users in these segments. Segment IDs are the marketplace's external segment IDs.

Show child attributes

Réponse

Successful Response

forecasts

PublicCampaignForecastMetrics · object

requis

Campaign performance forecasts

Show child attributes

Général

Exemples d'enchères

Exemples de webhooks

Auctions

Events

Toptimize

Toppie API

Campaign API

Catalog API

Billing API

Reporting API

Invitation API

User API

Webhooks API

Assets API

Segments Service

Offsite Ads API

Forecasting Service

Media API

Placement API

Export API

API Reference

Banner Campaign Performance Forecasts

Autorisations

Corps

Réponse