Ads · Ad Insights
Returns the per-creative performance inside TikTok Smart+ ads, one page at a time. Works with TikTok Ads.
GET
https://api.pozy.ai/v1/ads/tiktok-smart-plus-materialsTikTokgetTikTokSmartPlusMaterialReport
Guides: TikTok Ads, Ads reporting
Request
Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the ads resource group disabled get 403 resource_group_disabled. Authentication
Query parameters
| Name | Type | Notes |
|---|---|---|
accountIdrequired | string | |
adAccountIdrequired | string | |
startDaterequired | string (date) | |
endDaterequired | string (date) | |
level | string | One of ad, adGroupDefault ad |
smartPlusAdIds | string | |
adGroupIds | string | |
page | integer | Default 1At least 1 |
pageSize | integer | Default 1001 to 1000 |
Example
curl -X GET "https://api.pozy.ai/v1/ads/tiktok-smart-plus-materials?accountId=696e0b682d0a31188e7a2ba9&adAccountId=666219aad7bab67ace411e4f&startDate=2026-10-01&endDate=2026-10-01" \
-H "Authorization: Bearer $POZY_API_KEY"const res = await fetch("https://api.pozy.ai/v1/ads/tiktok-smart-plus-materials?accountId=696e0b682d0a31188e7a2ba9&adAccountId=666219aad7bab67ace411e4f&startDate=2026-10-01&endDate=2026-10-01", {
headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);import os
import requests
resp = requests.get(
"https://api.pozy.ai/v1/ads/tiktok-smart-plus-materials",
headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
params={
"accountId": "696e0b682d0a31188e7a2ba9",
"adAccountId": "666219aad7bab67ace411e4f",
"startDate": "2026-10-01",
"endDate": "2026-10-01",
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())Response
200 on success
adAccountIdstringlevelstringOne of
ad,adGroup.startDatestringendDatestringpageintegerpageSizeintegertotalRowsintegertotalPagesintegermissingRowsintegerrowsarray of object7 child fields
materialIdstringmaterialTypestringCan be null.
tiktokItemIdstringCan be null.
namestringCan be null.
smartPlusAdIdstringCan be null.
adGroupIdstringCan be null.
metricsobject10 child fields
spendnumberCan be null.
impressionsnumberCan be null.
clicksnumberCan be null.
cpcnumberCan be null.
addToCartnumberCan be null.
initiateCheckoutnumberCan be null.
addPaymentInfonumberCan be null.
purchasesnumberCan be null.
purchaseValuenumberCan be null.
roasnumberCan be null.
200 response
{
"adAccountId": "666219aad7bab67ace411e4f",
"level": "ad",
"startDate": "string",
"endDate": "string",
"page": 1,
"pageSize": 1,
"totalRows": 42,
"totalPages": 42,
"missingRows": 1,
"rows": [
{
"materialId": "651e8a21ab6f7db5c340a60e",
"materialType": "string",
"tiktokItemId": "6194c6395799073f3c47a197",
"name": "Acme",
"smartPlusAdId": "6e8904b1093cf559921b85fe",
"adGroupId": "6ad180be375f36f2c328e52b",
"metrics": {
"spend": 12.5,
"impressions": 12.5,
"clicks": 12.5,
"cpc": 12.5,
"addToCart": 12.5,
"initiateCheckout": 12.5,
"addPaymentInfo": 12.5,
"purchases": 12.5,
"purchaseValue": 12.5,
"roas": 12.5
}
}
]
}Errors
Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:
| 400 | invalid_request_error | A parameter or body field is missing or invalid. param names it. |
| 401 | authentication_error | The API key is missing, revoked or expired. |
| 403 | permission_error | The key is scoped to other profiles or has this resource group disabled. |
| 429 | rate_limit_error | Too many requests this minute. Wait for Retry-After seconds. |
Every code is listed in Errors.