Developer resources

Get inventory estimates — TikTok Business API

Get inventory estimates · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Open in the API index TikTok Business platform page

Get inventory estimates

GET/rf/inventory/estimate/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/rf/inventory/estimate/

Description

Use this endpoint to get inventory estimates for Reach & Frequency ads.

See About Reach & Frequency - Inventory estimate for more details about inventory estimate and the mapping between the prediction results returned via this endpoint and the results on TikTok Ads Manager.

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/rf/inventory/estimate/

Authentication & shop

Name	In	Type	Sample	Description
Authorization	header	header	Bearer q360_live_ab12cd34_…	Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_id	query	string	7000000000000000001	Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

Name	In	Type	Required	Description
audience_info	query	object	Yes	Audience targeting rules
schedule_start_time	query	string	Yes	Start time (UTC+0): format "YYYY-MM-DD HH:MM:SS". The HH:MM:SS value must be equal to 00:00:00 for the target region. For example, 2020-10-24 05:00:00 is equal to 2020-10-24 00:00:00 in the UTC-5 time zone. Note: If the targeting locations (`location_ids`) you specify observe Daylight Saving Time, ignore Daylight Saving Time and pass in Standard Time. For example, if you want to start the schedule for the Netherlands at `2022-04-02 00:00:00` local time (Daylight Saving Time has started, UTC+2 timezone), you need to regard the time zone of the Netherlands as Standard Time Zone (UTC+1) and specify this field as `2022-04-02 23:00:00`.
schedule_end_time	query	string	Yes	End time (UTC+0): format "YYYY-MM-DD HH:MM:SS". The HH:MM:SS value must be equal to 23:59:59 for the target region. For example, 2020-11-11 04:59:59 is equal to 2020-11-10 23:59:59 in the UTC-5 time zone. The time interval between `schedule_end_time` and `schedule_start_time` must not exceed 30 days. Note: If the targeting locations (`location_ids`) you specify observe Daylight Saving Time, ignore Daylight Saving Time and pass in Standard Time. For example, if you want to end the schedule for the Netherlands at `2022-11-02 23:59:59` local time (Daylight Saving Time has started, UTC+2 timezone) , you need to regard the time zone of the Netherlands as Standard Time Zone (UTC+1) and specify this field as `2022-11-02 22:59:59`.
frequency	query	number	Yes	Frequency. This parameter, together with the `frequency_schedule` parameter, determines the upper limit for how frequently an ad is shown to users (only for R&F ads). For example, if `frequency` = 2 and `frequency_schedule` = 3, it means the ad will be displayed at most twice every 3 days. The following conditions should be met: - 1 ≤ `frequency` ≤ `frequency_schedule` - 1 ≤ `frequency_schedule` ≤ min(`schedule_end_time` - `schedule_start_time`, 30). - The frequency cap determined by `frequency` and `frequency_schedule` does not exceed four times a day.
frequency_schedule	query	number	Yes	Frequency cycle (in days). This parameter, together with the `frequency` parameter, determines the upper limit for how frequently an ad is displayed to users (only for R&F ads). Please see the description for the `frequency` field.
objective_type	query	string	Yes	The advertising objective. Enum values: `RF_REACH`.
cpv_video_duration	query	string	No	The target video view duration. Enum values: `SIX_SECONDS`, `TWO_SECONDS`.
feed_type	query	string	No	Feed type option. Enum values: `STANDARD_FEED`, `TOP_FEED`. `STANDARD_FEED` refers to large inventory with normal CPM price while `TOP_FEED`refers to limited inventory with higher CPM price.
rf_purchased_type	query	string	No	Buying type. Allowed values: - `FIXED_SHOW`: Purchase to achieve a fixed amount of impressions. - `FIXED_REACH`: Purchase to reach a fixed number of users. - `FIXED_BUDGET`: Purchase with a fixed budget.
budget	query	float	No	Budget. Required when `rf_purchased_type` = `FIXED_BUDGET`. Based on the budget amount that you specify, we will return the estimated values for other fields.
purchased_impression	query	number	No	Impressions to be purchased, in the unit of 1,000. Required when `rf_purchased_type` = `FIXED_SHOW`. Based on the impression amount that you specify, we will return the estimated values for other fields.
purchased_reach	query	number	No	Number of users reached to be purchased, in the unit of 1,000. Required when `rf_purchased_type` = `FIXED_REACH`. Based on the reach amount that you specify, we will return the estimated values for other fields.
rf_campaign_type	query	string	No	When `objective_type` is specified as `RF_REACH`, use this field to set the campaign as a TikTok Pulse campaign, then you can get available premium contextual tags. Enum values: `STANDARD` (Reach & Frequency campaign), `PULSE` (TikTok Pulse campaign). If you set this field as `PULSE`, only one location ID (`location_id`) will be returned. Note: - Do not pass in this field when `objective_type` is not specified as `RF_REACH`. - You need to pass the `location_id` value returned in this endpoint to `location_ids` when you use /adgroup/rf/create/ to create a TikTok Pulse ad group.

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/rf/inventory/estimate/?audience_info=%7B%22location_ids%22%3A%5B%5D%7D&schedule_start_time=&schedule_end_time=&frequency=0&frequency_schedule=0&objective_type=" \
  -H "Authorization: Bearer $KEY"

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/tiktok_business/rf/inventory/estimate/",
    params={
        "audience_info": {
            "location_ids": []
        },
        "schedule_start_time": "",
        "schedule_end_time": "",
        "frequency": 0,
        "frequency_schedule": 0,
        "objective_type": ""
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())

Node.js

const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/rf/inventory/estimate/');
for (const [k, v] of Object.entries({"audience_info":{"location_ids":[]},"schedule_start_time":"","schedule_end_time":"","frequency":0,"frequency_schedule":0,"objective_type":""})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());

PHP

<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/rf/inventory/estimate/' . '?' . http_build_query(['audience_info' => '{"location_ids":[]}', 'schedule_start_time' => '', 'schedule_end_time' => '', 'frequency' => 0, 'frequency_schedule' => 0, 'objective_type' => '']);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

Name	Type	Description
code	number	Return code. For the complete list of response codes and descriptions, see Appendix - Return Codes.
message	string	Return message. For details, see Appendix - Return Codes.
request_id	string	The log id of a request, which uniquely identifies the request.
data	object	Returned data.
default_result	object	Estimated inventory result. If you have specified a fixed value for `purchased_impression`, `budget`or `purchased_reach` in request, depending on the fixed value you have specified, we will return the corresponding predicted values in the `default_result` object in the response. For example, if you set `rf_purchased_type` to `FIXED_SHOW` and specify a fixed value in `purchased_impression`, then based on the impressions you set, we will calculate and return the estimated values for `budget`, `cpm`, `reach` and `average_frequency` in `default_result`.
base_info	object	Basic information.
budget	float	Total budget.
cpm	float	CPM (Cost per mille). Formula: `cpm` = `budget` / `impression`.
impression	number	Total impressions, in the unit of 1,000. For example, the value of 110 for this field represents 110,000 impressions.
reach	number	Number of users reached, in the unit of 1,000. For example, the value of 110 for this field represents 110,000 users reached.
max_reach	number	Number of total bookable reach based on the specified feed type, targeting settings and campaign duration, in the unit of 1,000. For example, the value of 200 in this field represents an available inventory of 200,000 users.
average_frequency	float	Formula: impressions per person (`average_frequency`) = total impressions (`impression`)/ numbers of users reached (`reach`).
daily_cost	object	Daily spend.
cost	float	Spend for the day.
date	string	Date. Format: `"YYYY-MM-DD"`. Example: `"2024-01-01"`.
frequency_per_person	object	Distribution of impressions per person. Note: When the frequency cap determined by `frequency` and `frequency_schedule` in the request exceeds four times a day, the value for the `frequency_per_person` will remain unchanged.
frequency	number	Impressions per person.
percentage	float	The percentage of users for the `frequency`. For example, if `frequency` is `1` and `percentage` is `0.42304230423042305`, then around 42.3% users will be shown the ad once.
results	object[]	Estimated inventory results for different budgets. In each result, the estimated impression, CPM, reach, frequency, daily cost, and frequency per person will be provided for the budget. The data structure for this object is the same as that of `default_result`.
base_info	object	Basic information.
budget	float	Total budget.
cpm	float	CPM (Cost per mille). Formula: `cpm` = `budget` / `impression`.
impression	number	Total impressions, in the unit of 1,000. For example, the value of 110 for this field represents 110,000 impressions.
reach	number	Number of users reached, in the unit of 1,000. For example, the value of 110 for this field represents 110,000 users reached.
average_frequency	float	Formula: impressions per person (`average_frequency`) = total impressions (`impression`)/ numbers of users reached (`reach`).
daily_cost	object	Daily spend.
cost	float	Spend for the day.
date	string	Date. Format: `"YYYY-MM-DD"`. Example: `"2024-01-01"`.
frequency_per_person	object[]	Distribution of impressions per person. Note: When the frequency cap determined by `frequency` and `frequency_schedule` in the request exceeds four times a day, the value for the `frequency_per_person` will remain unchanged.
frequency	number	Impressions per person.
percentage	float	The percentage of users for the frequency. For example, if `frequency` is `1` and `percentage` is `0.42304230423042305`, then around 42.3% users will be shown the ad once.

Response sample

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "default_result": {
            "daily_cost": [
                {
                    "date": "2020-08-07",
                    "cost": 3587.5169107559
                },
                {
                    "date": "2020-08-08",
                    "cost": 3565.1767601342
                },
                {
                    "date": "2020-08-09",
                    "cost": 3512.4961871912
                },
                {
                    "date": "2020-08-10",
                    "cost": 3537.1785786238
                }
            ],
            "frequency_per_person": [
                {
                    "percentage": 0.28,
                    "frequency": 1
                },
                {
                    "percentage": 0.72,
                    "frequency": 2
                }
            ],
            "base_info": {
                "impression": 5157,
                "average_frequency": 1.72,
                "reach": 2991,
				"max_reach": 17291,
                "cpm": 2.75,
                "budget": 14202.37
            }
        },
        "results": [
            {
                "daily_cost": [
                    {
                        "date": "2020-08-07",
                        "cost": 163.09
                    },
                    {
                        "date": "2020-08-08",
                        "cost": 163.27
                    },
                    {
                        "date": "2020-08-09",
                        "cost": 168.63
                    },
                    {
                        "date": "2020-08-10",
                        "cost": 164.8
                    }
                ],
                "frequency_per_person": [
                    {
                        "percentage": 0.2480487252,
                        "frequency": 1
                    },
                    {
                        "percentage": 0.7519512748,
                        "frequency": 2
                    }
                ],
                "base_info": {
                    "impression": 418,
                    "average_frequency": 1.75,
                    "reach": 239,
                    "cpm": 1.58,
                    "budget": 659.8
                }
           }
       ]
   }
(/code);

Get started

Sign up for Partner
Enable a data type of the Ads (Marketing API) group on the platform page
Create an API key (tick the TikTok Business channel)
Call it as in the examples above