Ad Insights

Per-creative performance inside TikTok Smart+ ads

Changed on

Breaks a Smart+ ad (or ad group) down by creative material, one row per Spark post, video or image, from TikTok's Smart+ material report. For a Spark post tiktokItemId is the TikTok post id.

Metrics

Conversion metrics are TikTok web (pixel) events. purchases, purchaseValue and roas come from Complete Payment, or from Place an Order (legacy ON_WEB_ORDER pixels) when that reports more; the two are never summed.

Metrics TikTok returns empty come back as null.

Rows

TikTok allows two dimensions per report, so rows are keyed by the Smart+ ad (level=ad) or by the ad group (level=adGroup), not both.

  • At level=ad a row is identified by smartPlusAdId + materialId.
  • At level=adGroup a row is identified by adGroupId + materialId.

Each row appears once across all pages.

Sorting and paging

Rows are sorted by spend descending, then the Smart+ ad or ad group id, then materialId.

The full result is cached for 10 minutes per account, advertiser and query. So pages read within that window are consistent and totalRows counts distinct rows.

How rows are read

  • When the unfiltered report fits one page (100 rows or fewer), it is served as is.
  • When the result spans more than one TikTok page, it is read per Smart+ ad (or ad group) listed on the advertiser, every status included. Those reads can return more rows than TikTok's unfiltered report declares, so totalRows can be larger than that count.

Short reads

Each TikTok read is checked against the row count it declares itself, and a short read is retried once.

  • A shortfall of at most 2 rows (or 1% of the rows, whichever is more) is served with missingRows set to that number.
  • A larger one answers 502 instead of a short result.
get/v1/ads/tiktok-smart-plus-materials

Request

  • Base URL
    https://zernio.com/api
  • Auth
    HTTP bearer

Query parameters

accountIdstring required

A tiktok or tiktokads account ID

adAccountIdstring required

TikTok advertiser ID

startDatestring date required

YYYY-MM-DD, in the advertiser's time zone

endDatestring date required

YYYY-MM-DD, on or after startDate

level'ad' | 'adGroup'

Key each row by Smart+ ad or by ad group

smartPlusAdIdsstring

Comma-separated Smart+ ad ids to filter by (up to 100)

adGroupIdsstring

Comma-separated ad group ids to filter by (up to 100)

pageinteger
pageSizeinteger

Response

Material rows

adAccountIdstring
level'ad' | 'adGroup'
startDatestring
endDatestring
pageinteger
pageSizeinteger
totalRowsinteger
totalPagesinteger
missingRowsinteger

Rows TikTok declared that a read and its retry could not return. 0 when the result is complete.

Changes

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status