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/v1/toptimize/forecasting/campaigns/sponsored-brand

Sponsored Brand Campaign Performance Forecasts

cURL

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

200

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

Autorisierungen

Authorization · string · header · erforderlich

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 · erforderlich

Daily budget for the campaign

dateRange · PublicDateRange · object · erforderlich

Campaign date range

Show child attributes

targetRoas · number · erforderlich

Target Return on Ad Spend

campaignType · enum<string> · erforderlich

Campaign type (required)

Verfügbare Optionen: autobidding, manual

chargeType · enum<string> · erforderlich

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

Verfügbare Optionen: cpm, cpc

placements · PublicPlacementRequest · object[] · erforderlich

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.

Verfügbare Optionen: 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

Antwort

200

application/json

Successful Response

forecasts · PublicCampaignForecastMetrics · object · erforderlich

Campaign performance forecasts

Show child attributes

unavailableForecasts · PublicUnavailableForecast · object[]

Requested metrics that could not be forecast because the selected slots, placements or products, or the marketplace, have no history. Their entries in forecasts are null.

Show child attributes