TikTok Ads tools

TikTok ad accounts (advertisers) reachable with the connected TikTok Ads token: id, name, currency, timezone, status, and which one is selected for the current project. Read only; returns connected=false when no account is linked.

This tool takes no parameters.

TikTok campaigns of the connected ad account: campaign_id, name, objective_type, budget, budget_mode, operation_status. Use campaign_id values for the other tiktok tools.

TikTok ad groups with budget, bid, optimisation goal, targeting (locations, ages, gender, languages, interests, audiences), placements, schedule and dayparting.

TikTok ads: ad_id, name, ad group, status, format, text, video_id, landing page, call to action.

TikTok performance by campaign, ad group or ad for a date range: spend, impressions, clicks, CTR, CPM, CPC, conversions, cost per conversion, conversion rate, ROAS where available; optional daily breakdown and totals. Real data only; connected=false when no account.

Custom and lookalike audiences of the TikTok ad account: audience_id, name, type, size (cover_num), validity. Use audience_ids in update_tiktok_ad_group to assign them.

Videos in the TikTok ad account's asset library: video_id, file name, duration, size, preview and cover URLs. Use video_id in create_tiktok_ad or create_tiktok_whatsapp_campaign; add new videos from a public URL with upload_tiktok_video.

Suggested cover frames for a TikTok library video (file/video/suggestcover): id, preview url (valid one hour), size. Upload the chosen url with upload_tiktok_image to use it as the ad cover (image_ids). Read only.

Turn targeting names into TikTok ids: interest (tool/interest_category → interest_category_ids), behavior (tool/action_category → actions[].action_category_ids), interest_keyword (tool/interest_keyword/recommend → interest_keyword_ids), location (tool/targeting/search → location_ids / zipcode_ids, cities and provinces), region (tool/region → targetable countries for the objective). Read only.

Ad identities of the TikTok ad account (identity/get): identity_id, identity_type, display name, username, whether posts can be pulled. Pass identity_id/identity_type to create_tiktok_ad or list_tiktok_posts. Read only.

TikTok conversion pixels of the ad account (pixel/list): pixel_id, pixel_code, name, setup mode and tracked events. Use pixel_id for conversion ad groups and pixel_code for send_tiktok_conversion_event. Read only.

Welcome message templates for TikTok Direct Message ads (creative/auto_message/get): auto_message_id, title, greeting, suggested questions and review status. Pass auto_message_id to create_tiktok_ad. Read only.

TikTok instant lead forms of the ad account (page/get, LEAD_GEN): page_id, title, status, created/updated/published time and preview URL. Read only.

Question fields of a TikTok instant lead form (page/field/get): field keys, labels and types plus form metadata, to read collected lead answers correctly. Read only.

Download the leads collected by a TikTok instant form or lead ad (page/lead/task + page/lead/task/download; a ZIP file is unpacked to its CSV). Opens the download task, polls it for a few seconds and, once ready, returns a privacy-safe summary: total rows, question names, and the first rows (limit, default 20) with lead id, created time, ad, ad group, campaign and form ids plus MASKED answers (names cut to initials; e-mails, phone numbers and IBANs masked). The full unmasked CSV is stored in the account's private file area and returned only as download_url, a signed link valid for 15 minutes (the stored file is kept for 30 days, then deleted): give the link to the user, never paste the file content into the chat; if the file cannot be stored, only the masked summary is returned. If TikTok is still preparing the file it returns task_id: call again with the same page_id/ad_id and that task_id. region: where the ads ran (eu = EEA/Switzerland/UK, us, other). Only ad account admins can download. Personal data: use only under the consent given on the form. Read only.

Creative portfolios of the TikTok ad account (creative/portfolio/list): portfolio id, type (display card, download card, gift code…), preview URL and main settings. Read only.

TikTok Shop stores linked to the ad account (gmv_max/store/list) with GMV Max availability, status, role, authorising Business Center and targetable regions. Read only.

Smart+ (automated) campaigns, ad groups or ads of the TikTok ad account (smart_plus/*/get). These are not returned by list_tiktok_campaigns / _ad_groups / _ads. Read only.

Organic TikTok posts of a linked TikTok account identity (identity/video/get) that can run as Spark Ads: tiktok_item_id, text, status, duration, cover and ad authorisation status. Read only.

TikTok's own ad group diagnoses and suggestions (tool/diagnosis/get): creative fatigue, bid and budget suggestions with estimated uplift, and event tracking problems. Read only; apply with the update tools.

Free-form TikTok report (report/integrated/get): any supported metrics and dimensions, report type, data level, date range or lifetime and filters. Rows are returned exactly as TikTok computes them. Read only.

TikTok Business Centers reachable with the connected token (bc/get): bc_id, name, company, status, currency, timezone and your role. Read only.

This tool takes no parameters.

Ad accounts inside a TikTok Business Center (bc/asset/get, ADVERTISER): advertiser id, name, account type, your role and verification status. Read only.

Pixels held in a TikTok Business Center (bc/asset/get, PIXEL), across its ad accounts. Read only.

Asset groups of a TikTok Business Center (bc/asset_group/list): asset_group_id and name. Read only.

Business qualifications in a TikTok Business Center (bc/advertiser/qualification/get): company name, verification status, owning ad account, linked account count and region. Read only.

Activity log of a TikTok Business Center (changelog/get): when, which activity type, operator id and the change text, newest first. Read only.

Choose which TikTok ad account (advertiser) all further TikTok reads and writes use. Per project: with a non-default project selected only that project's advertiser is saved; in the default project the connection's selection changes. Local setting; nothing is changed on TikTok. Switching is always allowed; adding another advertiser on the platform is subject to the plan's ads.accounts.max limit (error=entitlement body with next_plan and upgrade_url).

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Upload a video to the TikTok ad account's asset library from a public URL (file/video/ad/upload, UPLOAD_BY_URL). Applied directly when the user asks; the new video_id is returned in the action result.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Upload an image (image ad or video cover) to the TikTok asset library from a public URL (file/image/ad/upload, UPLOAD_BY_URL). Applied directly when the user asks; the image_id is returned in the action result.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a TikTok campaign end to end (campaign + ad group, optionally the ad) as a paused draft. Writes a ledger draft and sends it to TikTok directly when the user asks (the result shows the preview); only with a connected account.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a TikTok ad group under a campaign with budget, bid, targeting, placements, schedule and dayparting. Applied directly when the user asks; created paused unless operation_status=ENABLE.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a TikTok ad in an ad group from a library video (or Spark post). Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Change the budget of one or more TikTok campaigns (amount in the ad account currency). The preview reads the current budget from TikTok (from) so the +50% per change guardrail applies; applied directly when the user asks. The ledger is updated only when TikTok accepts.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Pause (DISABLE), enable (ENABLE) or permanently delete (DELETE) TikTok campaigns. Applied directly when the user asks; DELETE is applied only when the user explicitly asked for it and marks the ledger campaign as ended.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Update one or many TikTok ad groups at once: budget, bid (bid_type/bid_price), targeting (locations, ages, gender, languages, interests, audiences), schedule and dayparting, comment/share settings, frequency cap, brand safety and device/network targeting. Placements, budget mode and the optimisation setup (goal, billing event, optimisation event, pixel) are fixed at creation, so they are refused with the reason. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Pause, enable or permanently delete (DELETE) TikTok ad groups (e.g. pause the ones whose CPA is above target). Applied directly; DELETE only when the user explicitly asked.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Pause, enable or permanently delete (DELETE) TikTok ads (e.g. pause a fatigued creative). Applied directly; DELETE only when the user explicitly asked.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a rule-based TikTok custom audience from pixel, app or engagement events (e.g. added to cart in the last 30 days but did not purchase). Applied directly when the user asks; the audience needs hours to populate.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a TikTok lookalike audience from a custom audience (TikTok sizes: NARROW ≈ closest, BALANCED, BROAD). Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a TikTok ad that opens a WhatsApp chat (click-to-WhatsApp): LEAD_GENERATION campaign, ad group with optimisation location Instant Messaging App (WhatsApp) on TikTok placement, and a video ad whose cover is taken from the video automatically. chat_link builds the wa.me link from the phone number; website URLs are refused. Everything is created paused; applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Rename a TikTok campaign (campaign/update); the ledger name follows. Applied directly when the user asks. Budget and status have their own tools.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Edit a TikTok ad's copy in place (ad/update): name, text, landing page, call to action or display name. The current ad is read first and every other field is kept. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a welcome message for TikTok Direct Message ads (creative/auto_message/create): a greeting plus 1-3 tappable questions with automatic answers. Returns auto_message_id.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a custom TikTok ad identity (identity/create): the display name and avatar shown on non-Spark ads. Applied directly when the user asks; returns identity_id.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a TikTok conversion pixel (pixel/create). Applied directly when the user asks; returns pixel_id and pixel_code to install on the website.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Build a TikTok custom audience from a customer list (dmp/custom_audience/file/upload + create). Values are normalised and SHA-256 hashed inside Tecrube before anything is stored or sent; the preview shows counts only. Approval first.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Share TikTok custom audiences with other ad accounts in the same Business Center, or stop sharing (dmp/custom_audience/share, /share/cancel). Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Negative keywords of TikTok search ads for a campaign or ad group (search_ad/negative_keyword/*): list reads directly; add and delete are applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Send one server-side web conversion event to TikTok (Events API 2.0, event/track). Email, phone and external id are SHA-256 hashed before storing or sending. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.