TikTok

1. Authenticate
2. Verify your setup
3. Discover your advertisers
4. Explore campaigns
5. Pull a performance report
6. Export to CSV
TikTok Guide
TikTok Auth, Config & Output
TikTok Accounts & Objects
TikTok Reports & Insights
TikTok Creative Assets & Tracking
TikTok Workflows

Step 01

Authenticate

TikTok requires an app ID, app secret, access token, and refresh token. Store the full set once in your OS credential store:

Primary command

Authenticate

bash

agent-ads tiktok auth set --full

This prompts for app ID, app secret, and access token. Refresh token is optional.

Or set shell variables:

bash

export TIKTOK_ADS_ACCESS_TOKEN=abc123...
export TIKTOK_ADS_REFRESH_TOKEN=refresh123...
export TIKTOK_ADS_APP_ID=your_app_id
export TIKTOK_ADS_APP_SECRET=your_app_secret

TikTok access tokens expire every 24 hours. Refresh with stored or shell-provided app credentials:

bash

agent-ads tiktok auth refresh

Step 02

Verify your setup

Add --api to also ping the TikTok API and confirm your token works.

Primary command

Verify your setup

bash

agent-ads tiktok doctor

Add --api to also ping the TikTok API and confirm your token works.

Step 03

Discover your advertisers

Primary command

Discover your advertisers

bash

agent-ads tiktok advertisers list \
  --app-id $TIKTOK_ADS_APP_ID \
  --app-secret $TIKTOK_ADS_APP_SECRET

Step 04

Explore campaigns

Primary command

Explore campaigns

bash

agent-ads tiktok campaigns list --advertiser-id 1234567890

Step 05

Pull a performance report

Primary command

Pull a performance report

bash

agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions campaign_id \
  --metrics spend,impressions,clicks,ctr \
  --start-date 2026-03-01 \
  --end-date 2026-03-16

Step 06

Export to CSV

Primary command

Export to CSV

bash

agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions campaign_id \
  --metrics spend,impressions,clicks \
  --start-date 2026-03-01 \
  --end-date 2026-03-16 \
  --format csv \
  --output report.csv

Reference

TikTok guides

6 guides — exact flags, auth details, and workflow notes.

Guide

TikTok Guide

This is the routing guide for the TikTok provider. Read this first when the user wants to work with TikTok Ads. Then load only the specific reference file linked below.

Route to the Right Reference

Task	First command	Reference file
Set up auth, check config, refresh tokens	`agent-ads tiktok doctor`	tiktok-auth.md
List advertisers and account info	`agent-ads tiktok advertisers list`	tiktok-accounts-and-objects.md
List campaigns, ad groups, or ads	`agent-ads tiktok campaigns list --advertiser-id <id>`	tiktok-accounts-and-objects.md
Run a performance report (sync)	`agent-ads tiktok insights query ...`	tiktok-reports.md
Manage async report tasks	`agent-ads tiktok report-runs submit/status/cancel`	tiktok-reports.md
Search video/image creative assets	`agent-ads tiktok creatives videos --advertiser-id <id>`	tiktok-creative-and-tracking.md
List pixels or audiences	`agent-ads tiktok pixels list --advertiser-id <id>`	tiktok-creative-and-tracking.md
Follow an end-to-end recipe	—	tiktok-workflows.md

Load only the reference file you need. Do not preload all of them.

Pagination

TikTok uses page-number pagination (not cursor-based like Meta):

Flag	What it does
`--page <n>`	Page number (1-indexed)
`--page-size <n>`	Items per page
`--all`	Auto-follow all pages
`--max-items <n>`	Stop after N items

Common Mistakes

Forgetting TIKTOK_ADS_ACCESS_TOKEN before running API commands
Not passing --advertiser-id and not setting TIKTOK_ADS_DEFAULT_ADVERTISER_ID
Using --cursor (that's Meta) instead of --page (TikTok)
TikTok tokens expire every 24 hours — use agent-ads tiktok auth refresh to rotate
Not providing --app-id / --app-secret for advertisers list (the OAuth endpoint requires them)

Guide

TikTok Auth, Config & Output

TikTok uses the custom Access-Token HTTP header (not Bearer, not query param).

First command

TikTok Auth, Config & Output

bash

# Option 1: Store app credentials plus access token
agent-ads tiktok auth set --full
# Prompts for app ID, app secret, access token, then optional refresh token

# Option 2: Store both access and refresh tokens
agent-ads tiktok auth set --refresh-token
# Prompts for access token, then refresh token

# Option 3: Pipe from stdin
echo "$TOKEN" | agent-ads tiktok auth set --stdin

# Option 3b: Pipe both access + refresh tokens from stdin
printf '%s\n%s\n' "$ACCESS_TOKEN" "$REFRESH_TOKEN" | \
  agent-ads tiktok auth set --stdin --refresh-token

# Option 3c: Pipe app ID, app secret, access token, and optional refresh token
printf '%s\n%s\n%s\n%s\n' "$APP_ID" "$APP_SECRET" "$ACCESS_TOKEN" "$REFRESH_TOKEN" | \
  agent-ads tiktok auth set --stdin --full

# Option 4: Shell env (CI / ephemeral)
export TIKTOK_ADS_ACCESS_TOKEN=your_token_here

Authentication

TikTok uses the custom Access-Token HTTP header (not Bearer, not query param).

Token lifecycle

Access tokens expire every 24 hours
Refresh tokens expire after 1 year
Use agent-ads tiktok auth refresh to rotate tokens automatically

Setting up auth

bash

# Option 1: Store app credentials plus access token
agent-ads tiktok auth set --full
# Prompts for app ID, app secret, access token, then optional refresh token

# Option 2: Store both access and refresh tokens
agent-ads tiktok auth set --refresh-token
# Prompts for access token, then refresh token

# Option 3: Pipe from stdin
echo "$TOKEN" | agent-ads tiktok auth set --stdin

# Option 3b: Pipe both access + refresh tokens from stdin
printf '%s\n%s\n' "$ACCESS_TOKEN" "$REFRESH_TOKEN" | \
  agent-ads tiktok auth set --stdin --refresh-token

# Option 3c: Pipe app ID, app secret, access token, and optional refresh token
printf '%s\n%s\n%s\n%s\n' "$APP_ID" "$APP_SECRET" "$ACCESS_TOKEN" "$REFRESH_TOKEN" | \
  agent-ads tiktok auth set --stdin --full

# Option 4: Shell env (CI / ephemeral)
export TIKTOK_ADS_ACCESS_TOKEN=your_token_here

Token refresh

bash

# Refresh using stored refresh token + app credentials
agent-ads tiktok auth refresh \
  --app-id YOUR_APP_ID \
  --app-secret YOUR_APP_SECRET

# Or use env vars
export TIKTOK_ADS_APP_ID=your_app_id
export TIKTOK_ADS_APP_SECRET=your_app_secret
export TIKTOK_ADS_REFRESH_TOKEN=your_refresh_token
agent-ads tiktok auth refresh

auth refresh resolves app ID, app secret, and refresh token from CLI flags first, then shell env, then the OS credential store.

This stores the new access token (and updated refresh token) in the OS credential store.

Auth commands

Command	What it does
`agent-ads tiktok auth set`	Store access token
`agent-ads tiktok auth set --refresh-token`	Store both tokens
`agent-ads tiktok auth set --full`	Store app credentials plus access token, with optional refresh token
`agent-ads tiktok auth status`	Show credential source and storage status
`agent-ads tiktok auth delete`	Delete all stored TikTok credentials
`agent-ads tiktok auth refresh [--app-id ... --app-secret ...]`	Rotate access token

Configuration

Config file

Add a providers.tiktok section to agent-ads.config.json:

json

{
  "providers": {
    "tiktok": {
      "api_base_url": "https://business-api.tiktok.com",
      "api_version": "v1.3",
      "timeout_seconds": 60,
      "default_advertiser_id": "1234567890",
      "output_format": "json"
    }
  }
}

Environment variables

Variable	Default	Purpose
`TIKTOK_ADS_ACCESS_TOKEN`	—	Short-lived access token
`TIKTOK_ADS_REFRESH_TOKEN`	—	Long-lived refresh token
`TIKTOK_ADS_APP_ID`	—	App ID (for refresh and advertiser list)
`TIKTOK_ADS_APP_SECRET`	—	App secret (for refresh and advertiser list)
`TIKTOK_ADS_API_BASE_URL`	`https://business-api.tiktok.com`	Override API base URL
`TIKTOK_ADS_API_VERSION`	`v1.3`	Override API version
`TIKTOK_ADS_TIMEOUT_SECONDS`	`60`	HTTP timeout
`TIKTOK_ADS_DEFAULT_ADVERTISER_ID`	—	Default advertiser for all commands
`TIKTOK_ADS_OUTPUT_FORMAT`	`json`	Default output format

Config commands

Command	What it does
`agent-ads tiktok config path`	Show resolved config file path
`agent-ads tiktok config show`	Show full resolved configuration
`agent-ads tiktok config validate`	Validate config file

Doctor

bash

# Basic check
agent-ads tiktok doctor

# With live API ping (requires default_advertiser_id)
agent-ads tiktok doctor --api

TikTok API Response Format

All TikTok API responses have this envelope:

json

{
  "code": 0,
  "message": "OK",
  "request_id": "...",
  "data": { ... }
}

code: 0 = success
code: 20001 = partial success
code: 40xxx = client error (auth, params)
code: 50xxx = server error
code: 61000 = rate limited

The CLI strips this envelope and returns only the data field by default. Use --envelope to see metadata.

Guide

TikTok Accounts & Objects

Requires app credentials (the OAuth endpoint needs them):

First command

TikTok Accounts & Objects

bash

agent-ads tiktok advertisers list \
  --app-id YOUR_APP_ID \
  --app-secret YOUR_APP_SECRET

# Or with env vars
export TIKTOK_ADS_APP_ID=...
export TIKTOK_ADS_APP_SECRET=...
agent-ads tiktok advertisers list

Advertisers

List authorized advertisers

Requires app credentials (the OAuth endpoint needs them):

bash

agent-ads tiktok advertisers list \
  --app-id YOUR_APP_ID \
  --app-secret YOUR_APP_SECRET

# Or with env vars
export TIKTOK_ADS_APP_ID=...
export TIKTOK_ADS_APP_SECRET=...
agent-ads tiktok advertisers list

Get advertiser details

bash

agent-ads tiktok advertisers info \
  --advertiser-id 1234567890,9876543210

# With custom fields
agent-ads tiktok advertisers info \
  --advertiser-id 1234567890 \
  --fields display_name,company,status

Campaigns

bash

# List campaigns for an advertiser
agent-ads tiktok campaigns list --advertiser-id 1234567890

# With fields and pagination
agent-ads tiktok campaigns list \
  --advertiser-id 1234567890 \
  --fields campaign_id,campaign_name,budget,status \
  --page-size 50

# Auto-paginate all
agent-ads tiktok campaigns list \
  --advertiser-id 1234567890 \
  --all

# With filtering
agent-ads tiktok campaigns list \
  --advertiser-id 1234567890 \
  --filter '{"primary_status":"STATUS_ENABLE"}'

Ad Groups

bash

# List ad groups
agent-ads tiktok adgroups list --advertiser-id 1234567890

# With filtering by campaign
agent-ads tiktok adgroups list \
  --advertiser-id 1234567890 \
  --filter '{"campaign_ids":["123456"]}'

bash

# List ads
agent-ads tiktok ads list --advertiser-id 1234567890

# With fields
agent-ads tiktok ads list \
  --advertiser-id 1234567890 \
  --fields ad_id,ad_name,adgroup_id,status

Common Patterns

Default advertiser ID

Set TIKTOK_ADS_DEFAULT_ADVERTISER_ID or add default_advertiser_id to providers.tiktok in your config file to avoid repeating --advertiser-id on every command.

Filtering

TikTok filtering is a JSON object passed via --filter:

bash

# By status
--filter '{"primary_status":"STATUS_ENABLE"}'

# By IDs
--filter '{"campaign_ids":["123","456"]}'

# From a file
--filter-file filters.json

Pagination

TikTok uses page-number pagination:

bash

# Page 2, 50 items per page
--page 2 --page-size 50

# Auto-paginate everything
--all

# Stop after 100 items
--all --max-items 100

Guide

TikTok Reports & Insights

Use agent-ads tiktok insights query for on-demand reporting via the /report/integrated/get/ endpoint.

First command

TikTok Reports & Insights

bash

agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions stat_time_day \
  --metrics spend,impressions,clicks,cpc \
  --start-date 2026-03-01 \
  --end-date 2026-03-15

Synchronous Reporting

Use agent-ads tiktok insights query for on-demand reporting via the /report/integrated/get/ endpoint.

Basic usage

bash

agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions stat_time_day \
  --metrics spend,impressions,clicks,cpc \
  --start-date 2026-03-01 \
  --end-date 2026-03-15

Required parameters

Flag	Description
`--advertiser-id`	Advertiser ID (or set default)
`--report-type`	`BASIC`, `AUDIENCE`, `PLAYABLE_MATERIAL`, `CATALOG`
`--dimensions`	Comma-separated dimension columns
`--metrics`	Comma-separated metric columns

Optional parameters

Flag	Description
`--data-level`	`AUCTION_AD`, `AUCTION_ADGROUP`, `AUCTION_CAMPAIGN`, `AUCTION_ADVERTISER`
`--start-date`	Start date (YYYY-MM-DD)
`--end-date`	End date (YYYY-MM-DD)
`--filter`	JSON filter object
`--filter-file`	JSON file with filter
`--order-field`	Sort by this metric
`--order-type`	`ASC` or `DESC`
`--query-lifetime`	Query lifetime metrics
`--page` / `--page-size`	Pagination
`--all` / `--max-items`	Auto-paginate

Common dimension values

stat_time_day — daily breakdown
stat_time_hour — hourly breakdown
campaign_id — by campaign
adgroup_id — by ad group
ad_id — by ad
country_code — by country
gender — by gender
age — by age bucket

Common metric values

spend, impressions, clicks, cpc, cpm, ctr
conversion, cost_per_conversion, conversion_rate
reach, frequency
video_play_actions, video_watched_2s, video_watched_6s

Examples

bash

# Daily campaign spend for the last week
agent-ads tiktok insights query \
  --advertiser-id 123 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions stat_time_day,campaign_id \
  --metrics spend,impressions,clicks \
  --start-date 2026-03-11 --end-date 2026-03-18

# Lifetime metrics
agent-ads tiktok insights query \
  --advertiser-id 123 \
  --report-type BASIC \
  --data-level AUCTION_AD \
  --dimensions ad_id \
  --metrics spend,impressions,conversion \
  --query-lifetime

# Export to CSV
agent-ads tiktok insights query \
  --advertiser-id 123 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions stat_time_day \
  --metrics spend,impressions \
  --start-date 2026-03-01 --end-date 2026-03-15 \
  --format csv --output report.csv

Async Report Tasks

For large reports, use the async task API.

Create a task

bash

agent-ads tiktok report-runs submit \
  --advertiser-id 123 \
  --report-type BASIC \
  --data-level AUCTION_AD \
  --dimensions stat_time_day,ad_id \
  --metrics spend,impressions,clicks \
  --start-date 2026-01-01 --end-date 2026-03-01

Returns a task ID and a download URL when complete.

Check status

bash

agent-ads tiktok report-runs status \
  --advertiser-id 123 \
  --task-id TASK_ID_HERE

Cancel a task

bash

agent-ads tiktok report-runs cancel \
  --advertiser-id 123 \
  --task-id TASK_ID_HERE

The async report returns a download URL in the response data. Use curl or wget to fetch the file.

Guide

TikTok Creative Assets & Tracking

First command

TikTok Creative Assets & Tracking

bash

# List all video assets
agent-ads tiktok creatives videos --advertiser-id 1234567890

# With pagination
agent-ads tiktok creatives videos \
  --advertiser-id 1234567890 \
  --page-size 20 --all

# With filtering
agent-ads tiktok creatives videos \
  --advertiser-id 1234567890 \
  --filter '{"material_ids":["video123"]}'

Creative Assets

Search videos

bash

# List all video assets
agent-ads tiktok creatives videos --advertiser-id 1234567890

# With pagination
agent-ads tiktok creatives videos \
  --advertiser-id 1234567890 \
  --page-size 20 --all

# With filtering
agent-ads tiktok creatives videos \
  --advertiser-id 1234567890 \
  --filter '{"material_ids":["video123"]}'

Get image info

bash

# Get info for specific images
agent-ads tiktok creatives images \
  --advertiser-id 1234567890 \
  --image-id img123,img456

Pixels

List pixels

bash

agent-ads tiktok pixels list --advertiser-id 1234567890

# Auto-paginate
agent-ads tiktok pixels list \
  --advertiser-id 1234567890 \
  --all

Audiences

List custom audiences

bash

agent-ads tiktok audiences list --advertiser-id 1234567890

# With pagination
agent-ads tiktok audiences list \
  --advertiser-id 1234567890 \
  --page-size 50 --all

Guide

TikTok Workflows

End-to-end recipes for TikTok Ads. Each workflow is a sequence of commands you can run in order.

First command

TikTok Workflows

bash

# Step 1: List your advertisers (requires app credentials)
agent-ads tiktok advertisers list \
  --app-id $TIKTOK_ADS_APP_ID \
  --app-secret $TIKTOK_ADS_APP_SECRET

# Step 2: Get details for a specific advertiser
agent-ads tiktok advertisers info --advertiser-id 1234567890

# Step 3: List campaigns
agent-ads tiktok campaigns list --advertiser-id 1234567890

1. Account Discovery

Start from your token and discover all advertisers:

bash

# Step 1: List your advertisers (requires app credentials)
agent-ads tiktok advertisers list \
  --app-id $TIKTOK_ADS_APP_ID \
  --app-secret $TIKTOK_ADS_APP_SECRET

# Step 2: Get details for a specific advertiser
agent-ads tiktok advertisers info --advertiser-id 1234567890

# Step 3: List campaigns
agent-ads tiktok campaigns list --advertiser-id 1234567890

2. Daily Performance Report

Pull daily campaign performance for a date range, exported as CSV:

bash

agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions stat_time_day,campaign_id \
  --metrics spend,impressions,clicks,cpc,ctr \
  --start-date 2026-03-01 \
  --end-date 2026-03-16 \
  --format csv \
  --output campaign-daily.csv

3. Ad-Level Report With Breakdowns

Detailed ad-level performance with demographic breakdowns:

bash

agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type AUDIENCE \
  --data-level AUCTION_AD \
  --dimensions ad_id,gender,age \
  --metrics spend,impressions,clicks,conversion \
  --start-date 2026-03-01 \
  --end-date 2026-03-16 \
  --all

4. Large Async Export

For reports too large for sync queries:

bash

# Step 1: Submit the async task
agent-ads tiktok report-runs submit \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_AD \
  --dimensions stat_time_day,ad_id \
  --metrics spend,impressions,clicks \
  --start-date 2026-01-01 \
  --end-date 2026-03-01

# Step 2: Check status (note the task_id from step 1)
agent-ads tiktok report-runs status \
  --advertiser-id 1234567890 \
  --task-id TASK_ID_HERE

# Step 3: When complete, the status response contains a download URL.
# Use curl or wget to fetch the file.

5. Creative and Tracking Audit

Inspect creative assets and tracking setup:

bash

# Step 1: List video creatives
agent-ads tiktok creatives videos --advertiser-id 1234567890 --all

# Step 2: Check pixels
agent-ads tiktok pixels list --advertiser-id 1234567890

# Step 3: List custom audiences
agent-ads tiktok audiences list --advertiser-id 1234567890 --all

6. CI / Automation Pattern

bash

#!/bin/bash
set -euo pipefail

# Refresh token (TikTok tokens expire every 24 hours)
agent-ads tiktok auth refresh \
  --app-id "$TIKTOK_ADS_APP_ID" \
  --app-secret "$TIKTOK_ADS_APP_SECRET"

# Verify setup
agent-ads tiktok doctor --api -q

# Pull report
agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions stat_time_day,campaign_id \
  --metrics spend,impressions,clicks \
  --start-date "$(date -d yesterday +%Y-%m-%d)" \
  --end-date "$(date +%Y-%m-%d)" \
  --format csv \
  --output /data/tiktok-yesterday.csv

echo "Report saved to /data/tiktok-yesterday.csv"

Exit codes make it safe in set -e scripts: 0 = success, 1 = transport/internal, 2 = config/argument, 4 = TikTok API error.

7. Piping and Composing

bash

# Pretty-print to less
agent-ads tiktok campaigns list --advertiser-id 1234567890 --pretty | less

# Filter with jq
agent-ads tiktok campaigns list --advertiser-id 1234567890 --all \
  | jq '.[] | select(.primary_status == "STATUS_ENABLE")'

# JSONL for line-by-line processing
agent-ads tiktok insights query \
  --advertiser-id 1234567890 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions campaign_id \
  --metrics spend,impressions \
  --start-date 2026-03-01 --end-date 2026-03-16 \
  --format jsonl | while IFS= read -r line; do
    echo "$line" | jq -r '.dimensions.campaign_id + ": $" + .metrics.spend'
  done