TikTok

Overview

The TikTok Core API mirrors TikTok's Business API 1:1 — campaigns, ad groups, ads, custom audiences, creative uploads, reporting and trending discovery.

advertiser_id is required by TikTok on nearly every endpoint and is forwarded exactly as you send it — Core API does not inject it for you. Discover it with GET /api/core/tiktok/accounts.

TikTok is rate-limited app-wide at 8 QPS. Every Core API call shares that budget with Analify's own dashboards and MCP tools, so batch where TikTok allows it and avoid tight polling loops.

API Endpoints

Accounts

GET /api/core/tiktok/accounts

Start here — returns the advertiser record, including the advertiser_id, currency and timezone every other endpoint needs.

curl "https://analify.scalyax.ai/api/core/tiktok/accounts?organizationId={organizationId}" \
  -H "Authorization: Bearer {anlfy_token}"

Reporting

GET /api/core/tiktok/insights/report

TikTok's single reporting endpoint, forwarded verbatim. Takes TikTok's own params: advertiser_id, report_type (BASIC/AUDIENCE), data_level (AUCTION_CAMPAIGN/AUCTION_ADGROUP/AUCTION_AD), dimensions (JSON array), metrics (JSON array), start_date, end_date, page, page_size.

curl -G "https://analify.scalyax.ai/api/core/tiktok/insights/report" \
  -H "Authorization: Bearer {anlfy_token}" \
  --data-urlencode "organizationId={organizationId}" \
  --data-urlencode "advertiser_id=7000000000000000000" \
  --data-urlencode "report_type=BASIC" \
  --data-urlencode "data_level=AUCTION_CAMPAIGN" \
  --data-urlencode 'dimensions=["campaign_id","stat_time_day"]' \
  --data-urlencode 'metrics=["spend","impressions","conversion"]' \
  --data-urlencode "start_date=2026-08-01" \
  --data-urlencode "end_date=2026-08-16"

TikTok daily trend data reaches back ~30 days only. That is TikTok's own ceiling, not an Analify limit — a wider start_date silently returns a shorter series.

Campaigns, ad groups and ads

TikTok splits reads and writes across separate paths (/campaign/get/ vs /campaign/update/), and Core API preserves that shape rather than folding them into one REST resource. Status changes are their own endpoint, not a field on update.

# List campaigns
curl "https://analify.scalyax.ai/api/core/tiktok/campaigns?organizationId={organizationId}&advertiser_id=7000000000000000000" \
  -H "Authorization: Bearer {anlfy_token}"

# Pause one — TikTok's own operation_status enum
curl -X POST "https://analify.scalyax.ai/api/core/tiktok/campaigns/status?organizationId={organizationId}" \
  -H "Authorization: Bearer {anlfy_token}" -H "Content-Type: application/json" \
  -d '{
    "advertiser_id": "7000000000000000000",
    "campaign_ids": ["1800000000000000000"],
    "operation_status": "DISABLE"
  }'

⚠️

Create, update, status and audience-delete routes change a live ad account. They require an API token with the write scope.

Ad groups follow the identical pattern via POST /api/core/tiktok/adgroups (create), /api/core/tiktok/adgroups/update and /api/core/tiktok/adgroups/status.

Ads follow the same shape one level down: POST /api/core/tiktok/ads creates an ad from an existing ad group's creatives, POST /api/core/tiktok/ads/update updates one (advertiser_id + adgroup_id + creatives[], TikTok's own AdupdateCreatives shape), and POST /api/core/tiktok/ads/status enables/disables/deletes by ad_ids (or aco_ad_ids) with the same operation_status enum as campaigns and ad groups.

# Disable an ad
curl -X POST "https://analify.scalyax.ai/api/core/tiktok/ads/status?organizationId={organizationId}" \
  -H "Authorization: Bearer {anlfy_token}" -H "Content-Type: application/json" \
  -d '{
    "advertiser_id": "7000000000000000000",
    "ad_ids": ["1810000000000000002"],
    "operation_status": "DISABLE"
  }'

Audiences

Five of the six audience routes are POSTs because TikTok models them that way — only details and insight-overlap are GETs. POST /api/core/tiktok/audiences/lookalike creates a lookalike from an existing source audience.

Creative uploads

upload-image and upload-video forward TikTok's own upload body (advertiser_id, upload_type, and either a file reference or image_url/video_url). Video processing is asynchronous — poll GET /api/core/tiktok/creatives/video-info for the processing state before attaching a video to an ad.

Error Shape

TikTok signals failures inside an HTTP 200 body, using a non-zero code field rather than a real status. Analify's client detects that and raises it, but TikTok exposes no structured status to map from — so every upstream TikTok failure surfaces as 502, carrying TikTok's own message. Notably, a rate-limit appears as a 502, not a 429.

{
  "success": false,
  "error": {
    "message": "Advertiser id is invalid.",
    "code": "TIKTOK_API_ERROR"
  }
}

Credential problems are caught before any TikTok call:

| TIKTOK_API_ERROR | 502 | Any failure reported by TikTok |