Analytics & Insights

Call GET /v1/ads/{adId}/analytics with the ad's _id for spend, impressions, clicks, CTR, CPM and video metrics.

Add breakdowns for a split by gender, age, country_code, platform, ac or language.

curl "https://zernio.com/api/v1/ads/66f0a1b2c3d4e5f6a7b8c9d0/analytics?fromDate=2027-01-04&toDate=2027-01-11&breakdowns=age" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"

Response (200), trimmed:

{
  "ad": { "id": "66f0a1b2c3d4e5f6a7b8c9d0", "name": "Boost viral video", "platform": "tiktok", "status": "active", "currency": "USD" },
  "analytics": {
    "summary": { "spend": 312.4, "impressions": 128400, "clicks": 2110, "ctr": 1.64, "cpc": 0.15, "cpm": 2.43, "videoPlayActions": 96200, "videoP100WatchedActions": 18400 },
    "daily": [ { "date": "2027-01-04", "spend": 44.1, "impressions": 18200, "clicks": 301 } ],
    "breakdowns": { "age": [ { "value": "AGE_18_24", "spend": 140.2, "impressions": 61000, "clicks": 1080 } ] }
  }
}

GET /v1/ads/tree rolls the same metrics up per campaign and ad group (Get campaign tree).

Offline conversions (in-store, CRM, call-center): POST /v1/ads/conversions on a tiktokads account sends them to TikTok's Offline Events API.

• destinationId is the Offline Event Set id.
• Each event must carry an email or phone.
• The connection must have granted the Offline Events permission. Older grants must reconnect.

Web-pixel events are not sent this way (Send conversions).

Live reports and de-duplicated reach

GET /v1/ads/insights runs TikTok's synchronous report live, for questions the synced metrics cannot answer.

The most common one is reach across a set. Adding the reach of two campaigns counts a person who saw both twice, and the synced numbers only hold per-entity reach.

Send these params:

reportType is BASIC (the default) or AUDIENCE.

filtering takes the same JSON array as Meta, [{"field", "operator", "value"}]. Use TikTok's field names (campaign_ids, adgroup_ids, ad_ids) and TikTok's filter type as operator, for example IN.

For de-duplicated reach, filter the set and group by country_code instead of the entity id. TikTok then counts each person once across the whole set and date range.

Two campaigns over a month:

curl -G "https://zernio.com/api/v1/ads/insights" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  --data-urlencode "accountId=66b2e19d8c3f5a7e9d0b1c2d" \
  --data-urlencode "adAccountId=7123456789012345678" \
  --data-urlencode "dataLevel=AUCTION_CAMPAIGN" \
  --data-urlencode "dimensions=country_code" \
  --data-urlencode "metrics=reach,impressions,frequency" \
  --data-urlencode "fromDate=2027-01-01" \
  --data-urlencode "toDate=2027-01-31" \
  --data-urlencode 'filtering=[{"field":"campaign_ids","operator":"IN","value":["1876574798182050","1876575504573650"]}]'

Response (200), trimmed:

{
  "adAccountId": "7123456789012345678",
  "data": [
    { "dimensions": { "country_code": "US" }, "metrics": { "reach": "17770000", "impressions": "41210000", "frequency": "2.32" } }
  ],
  "paging": { "page": 1, "pageSize": 100, "totalRows": 1, "totalPages": 1 }
}

Rows come back verbatim from TikTok, with metric values as strings. Page with page and pageSize (up to 1,000).

For a set of ads, use dataLevel=AUCTION_AD with ad_ids. For ad groups, use AUCTION_ADGROUP with adgroup_ids.

• Reach is per country. When the set delivers in several countries, summing the rows counts a person reached in two countries twice.
• The filter must match the data level or a coarser one. A finer filter, such as ad_ids at AUCTION_CAMPAIGN, answers 400: TikTok would silently widen it to every campaign containing those ads.
• AUCTION_ADVERTISER takes no entity filter.
• A 400 carries TikTok's own message when TikTok rejects the query (an unknown metric, a bad dimension combination), a 403 means the connection cannot read that advertiser, and a 429 is TikTok's rate limit.

Asynchronous report runs (POST /v1/ads/insights/reports) stay Meta only.