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

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

chargeType

enum<string>

requis

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

Options disponibles:

cpm,

cpc

placements

PublicPlacementRequest · object[]

requis

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.

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

Sponsored Brand Campaign Performance Forecasts

Autorisations

Corps

Réponse