Sponsored Brand Campaign Performance Forecasts

curl --request POST \
  --url https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/sponsored-brand \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dailyBudget": 123,
  "dateRange": {
    "startDate": "2023-12-25",
    "endDate": "2023-12-25"
  },
  "targetRoas": 123,
  "placements": [
    {
      "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/sponsored-brand"

payload = {
    "dailyBudget": 123,
    "dateRange": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25"
    },
    "targetRoas": 123,
    "placements": [
        {
            "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,
    placements: [{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/sponsored-brand', 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/sponsored-brand",
  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,
    'placements' => [
        [
                '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/sponsored-brand"

	payload := strings.NewReader("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"placements\": [\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/sponsored-brand")
  .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  \"placements\": [\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/sponsored-brand")

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  \"placements\": [\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

Sponsored Brand Campaign Performance Forecasts

Get performance forecasts with confidence intervals for sponsored brand campaigns.

Placement ids: each placements[].id is the external placement slug (auction-facing, max 256 characters). Up to 100 placements per request.

Campaign types:

autobidding: provide placements without bidAmount.
manual: every placement must include bidAmount > 0.

Charge type: cpm or cpc.

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

sponsored-brand

Sponsored Brand Campaign Performance Forecasts

curl --request POST \
  --url https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/sponsored-brand \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dailyBudget": 123,
  "dateRange": {
    "startDate": "2023-12-25",
    "endDate": "2023-12-25"
  },
  "targetRoas": 123,
  "placements": [
    {
      "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/sponsored-brand"

payload = {
    "dailyBudget": 123,
    "dateRange": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25"
    },
    "targetRoas": 123,
    "placements": [
        {
            "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,
    placements: [{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/sponsored-brand', 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/sponsored-brand",
  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,
    'placements' => [
        [
                '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/sponsored-brand"

	payload := strings.NewReader("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"placements\": [\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/sponsored-brand")
  .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  \"placements\": [\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/sponsored-brand")

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  \"placements\": [\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>"
    }
  ]
}

Authorizations

Authorization

string

header

required

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.

Body

application/json

dailyBudget

number

required

Daily budget for the campaign

dateRange

PublicDateRange · object

required

Campaign date range

Show child attributes

targetRoas

number

required

Target Return on Ad Spend

campaignType

enum<string>

required

Campaign type (required)

Available options:

autobidding,

manual

chargeType

enum<string>

required

Billing rail for the campaign: 'cpm' or 'cpc'.

Available options:

cpm,

cpc

placements

PublicPlacementRequest · object[]

required

Placements the sponsored brand campaign targets (required). Each id is the external placement slug.

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.

Available options:

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

Response

Successful Response

forecasts

PublicCampaignForecastMetrics · object

required

Campaign performance forecasts

Show child attributes

General

Auction examples

Webhook examples

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

Sponsored Brand Campaign Performance Forecasts

Authorizations

Body

Response