Get Spark Ads video recommendations for a Business Account
Use this endpoint to obtain the Spark Ads recommendation results for up to 20 TikTok video posts within your Business Account.
The recommendation results are generated by comparing the video posts with benchmarks that consider data on audience interactions, preferences, video post attributes (such as genre and length), and historical performance. Based on these factors, each video is assigned a recommendation score. Videos with higher scores indicate a greater likelihood of advertising success and receive a higher recommendation level.
To ensure meaningful results, we recommend retrieving recommendations for a Business Account with at least 20 posted videos. If your Business Account contains more than 20 video posts, only the top 20 videos with the highest potential for Spark Ads will be included in the response, while others will be filtered out.
Our recommendation model continuously evolves as it gathers more data, aiming to provide recommendations that are relevant and engaging for users. Regular evaluations are conducted to align the model's predictions with user behavior and improve its effectiveness over time.
Request
Endpoint https://business-api.tiktok.com/open_api/v1.3/business/video/recommend/
Method GET
Header
|Field{30%}|Data Type{15%}|Description{55%}|
|---|---|---|
|Access-Token {Required}|string|Access token authorized by the TikTok Business Account.<br><br>To obtain an access token, use [/tt_user/oauth2/token/](https://business-api.tiktok.com/portal/docs?id=1738084387220481#item-link-Get%20a%20TikTok%20account%20access%20token).|
Parameters
|Field{30%}|Data Type{15%}|Description{55%}|
|--- |--- |--- |
|business_id {Required}|string|Application specific unique identifier for the TikTok Business Account.<br><br>Pass the value of the `open_id` field returned in the response of [/tt_user/oauth2/token/](https://business-api.tiktok.com/portal/docs?id=1738084387220481#item-link-Get%20a%20TikTok%20account%20access%20token) to this field.|
|video_ids|string[]|<ul><li>If you want to have all videos under your Business Account analyzed, do not pass `video_ids` and `exclude_video_ids`.</li><li>If you want to narrow down the scope of videos that will be analyzed to generate recommendations, pass either `video_ids` or `exclude_video_ids`. <ul><li>The recommendation level (`recommendation_level`) for each video is relative to the provided video set. Different video sets might result in different recommendation levels for the same video.</li></ul></li></ul> <br>The ID list of videos for which you wish to receive recommendations only.<br><br>Max size: 20.<br><br>To get the IDs of public videos under your Business Account, use [/business/video/list/](1762228421622786.html).|
|exclude_video_ids|string[]|<ul><li>If you want to have all videos under your Business Account analyzed, do not pass `video_ids` and `exclude_video_ids`.</li><li>If you want to narrow down the scope of videos that will be analyzed to generate recommendations, pass either `video_ids` or `exclude_video_ids`. </li></ul> <br>The ID list of videos for which you don't wish to receive recommendations.<br><br>No max size limit.<br><br>To get the IDs of public videos under your Business Account, use [/business/video/list/](1762228421622786.html).|
|time|string|The time when the TikTok video posts were published.<br><br>Enum values:<ul><li>`PAST_ONE_MONTH`: In the past one month.</li><li>`PAST_THREE_MONTHS`: In the past three months.</li><li>`PAST_SIX_MONTHS`: In the past six months.</li></ul><br>Default value: `PAST_SIX_MONTHS`.|
|objective_type|string|The advertising objective for which to generate recommendations.<br><br>Enum values:<ul><li>`REACH`: Reach.</li><li>`TRAFFIC`: Traffic.</li><li>`VIDEO_VIEWS`: Video views.</li><li>`ENGAGEMENT`: Community interaction.</li><li>`APP_PROMOTION`: App promotion.</li><li>`LEAD_GENERATION`: Lead generation.</li><li>`WEB_CONVERSIONS`: Website conversions.</li><li>`PRODUCT_SALES`: Product sales.</li></ul><br>Default value: `REACH`. <br><br>If you specify this field, you can create a campaign with the same advertising objective (`objective_type`) value by using [/campaign/create/](1739318962329602.html) and use the recommended video post in your ads by setting `tiktok_item_id` to one of the recommended post IDs (`item_id`) in [/ad/create/](1739953377508354.html).|
Example
Consider all videos for recommendations
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/business/video/recommend/?business_id={{business_id}}' \
--header 'Access-Token: {{Access-Token}}' \
(/code)
Consider specific videos for recommendations
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/business/video/recommend/?business_id={{business_id}}&video_ids=["{{video_id}}","{{video_id}}"]' \
--header 'Access-Token: {{Access-Token}}' \
(/code)
Exclude specific videos from recommendations
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/business/video/recommend/?business_id={{business_id}}&exclude_video_ids=["{{exclude_video_id}}","{{exclude_video_id}}"]' \
--header 'Access-Token: {{Access-Token}}' \
(/code)
Response
|Field{30%}|Type{15%}|Description{55%}|
|---|---|---|
|code |number|Response code. For the complete list of response codes and descriptions, see [Appendix-Return Code](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). |
|message|string|Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097).|
|request_id |string|The log ID of a request, which uniquely identifies the request. |
|data |object|Returned data.|
#|videos|object[]|A list of up to 20 TikTok video posts with their Spark Ads recommendation results.|
##|recommendation_level|string|The recommendation level, which indicates the video's suitability for Spark Ads.<br><br>Enum values: <ul><li>`HIGH`: Highly recommended.</li><li>`MEDIUM`: Moderately recommended.</li><li>`LOW`: Not recommended.</li></ul>|
##|item_id|string|Unique identifier for the TikTok video post.<br><br>You can pass the value of this field to `tiktok_item_id` in [/ad/create/](1739953377508354.html) to create Spark Ads. To learn more about Spark Ads, see [Create Spark Ads](1739470744631298.html).<br><br>Example: `6995316737801538821`.<br><br>Updated in: Real-time|
##|embed_url|string|An embeddable link for this TikTok video.<br><br>Example: `https://www.tiktok.com/static/profile-video?id=7202758233486822657&hide_author=1&utm_campaign=tt4d_open_api&utm_source=7220548562860376066`.<br><br>Updated in: Real-time|
##|thumbnail_url|string|Temporary URL for the video thumbnail.<br><br>You need to re-acquire the URL after it expires. The expiration time is included in the URL after the `x-expires` parameter, in the format of an Epoch/Unix timestamp in seconds.<br><br>Example: `https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/75dec21d63500917fb6ec8bc59415156~c5_300x300.jpeg?x-expires=1614099600&x-signature=PmK%2BWs3LzSzRL2tYs%2FZx7EjG3Gk%3D`.<br><br>Updated in: Real-time|
##|create_time|string|The time when the video was published, in the format of an Epoch/Unix timestamp in seconds (UTC time).<br><br>Example: `1628461703`.<br><br>Updated in: Real-time|
##|video_views|number|Total number of video views for the video.<br><br><p><span style="color:darkred"><b>Note</b></span>: <ul><li>Counts when playback duration >0 and the playback is the first playback in an impression session.</li><li>If the user swipes away from the ad then swipes back, it would be counted as 2 impressions. Therefore, a new video view will be counted again with the new impression session.</li></ul><br>Example: 603.<br><br>Updated in: T + 24-48 hours (UTC time)|
##|likes|number|Total number of likes on the video.<br><br>Example: 243.<br><br>Updated in: T + 24-48 hours (UTC time)|
##|comments|number|Total number of comments on the video.<br><br>Example: 10.<br><br>Updated in: T + 24-48 hours (UTC time)|
##|shares|number|Total number of times the video has been shared.<br><br>The share count displayed in this field corresponds to the number of shares shown in the For You feed on the TikTok mobile app. It includes both external shares and internal shares sent to friends using the "Send to friends" button.<br>For example, if a video is shared externally 30 times and shared with friends within the TikTok app 20 times, the value of this field will be 50.<br><br>Example: 10.<br><br>Updated in: T + 24-48 hours (UTC time)|
##|audience_countries|object[]|Percentage breakdown of the top 10 countries or regions where viewers of the video are located.<br><br>Max size: 10.<br><br>Example: `[{"country":"CA","percentage":0.0132}, {"country":"GB","percentage":0.0987},{"country":"US","percentage":0.7303},...]`<br><br>Updated in: T + 24-48 hours (UTC time)<br><br><p><span style="color:darkred"><b>Note</b></span>: If the `video_views` of the video is less than 100, the value of this field will be an empty list (`[]`).|
###|country|string|[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) country code.|
###|percentage|float|Percentage of audience registered from a specified country or region.|
Example
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"videos": [
{
"shares": 0,
"thumbnail_url": "{{thumbnail_url}}",
"create_time": "{{create_time}}",
"recommendation_level": "MEDIUM",
"audience_countries": [],
"item_id": "{{item_id}}",
"video_views": 0,
"likes": 0,
"comments": 0,
"embed_url": "{{embed_url}}"
},
{
"shares": 0,
"thumbnail_url": "{{thumbnail_url}}",
"create_time": "{{create_time}}",
"recommendation_level": "MEDIUM",
"audience_countries": [],
"item_id": "{{item_id}}",
"video_views": 0,
"likes": 0,
"comments": 0,
"embed_url": "{{embed_url}}"
},
{
"shares": 0,
"thumbnail_url": "{{thumbnail_url}}",
"create_time": "{{create_time}}",
"recommendation_level": "LOW",
"audience_countries": [],
"item_id": "{{item_id}}",
"video_views": 4,
"likes": 3,
"comments": 1,
"embed_url": "{{embed_url}}"
}
]
}
}
(/code)