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>"
    }
  ]
}

Autorizações

Authorization

string

header

obrigatório

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.

Corpo

application/json

dailyBudget

number

obrigatório

Daily budget for the campaign

dateRange

PublicDateRange · object

obrigatório

Campaign date range

Show child attributes

targetRoas

number

obrigatório

Target Return on Ad Spend

campaignType

enum<string>

obrigatório

Campaign type (required)

Opções disponíveis:

autobidding,

manual

slots

PublicSlotRequest · object[]

obrigatório

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.

Opções disponíveis:

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

Resposta

Successful Response

forecasts

PublicCampaignForecastMetrics · object

obrigatório

Campaign performance forecasts

Show child attributes

Geral

Exemplos de leilões

Exemplos 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

Autorizações

Corpo

Resposta