# TikTok Ads through toolfare > CPA and ROAS by campaign or ad, TikTok’s integrated reports, Smart+ performance by creative material, GMV Max results by store and audience-size estimates — answered inside ChatGPT, Claude, Codex or Cursor. Connect your TikTok ad account to toolfare once; your AI reads it with your own login, and every read is free. Page: https://toolfare.ai/tiktok-ads ## Use it from your agent Paste this into Claude Code, Codex, Cursor or any agent with a shell: > Set up https://toolfare.ai/skill.md, then use toolfare to answer: What was our TikTok CPA by campaign last week? Apps without a terminal connect toolfare as an MCP server: https://toolfare.ai/docs#connect ## Use it from a script ```sh mkdir -p ~/.local/bin curl -fsSL 'https://toolfare.ai/toolfare/toolfare.mjs' -o ~/.local/bin/toolfare chmod +x ~/.local/bin/toolfare export PATH="$HOME/.local/bin:$PATH" export TOOLFARE_MCP_URL='https://api.toolfare.ai/mcp' toolfare login ``` Then connect your TikTok Ads account in the toolfare console (https://toolfare.ai/tiktok-ads#setup); calls fail until it is connected. Sign in once per machine; the CLI renews the sign-in itself. On a CI runner or another server, create an API key in the toolfare console and set it as `TOOLFARE_API_KEY` instead of signing in. Paid calls on one sign-in or key run one at a time. `--max-cost` refuses a call quoted above that many credits (1,000 credits = $3). ## Tools ### CPA and ROAS by campaign, ad group, ad or day Tool: `ads_query_single_dimension` Spend, clicks, conversions, CPA and ROAS, grouped by one dimension over a date range — read from toolfare’s synced copy of the account, so a month answers in one call. Ask: - What was our TikTok CPA by campaign last week? - Which TikTok ads had the lowest cost per conversion this month? ### TikTok’s integrated report, live Tool: `ads_get_insights` The same report TikTok’s own reporting API serves, at campaign, ad group or ad level, for the metrics and dates you name. Ask: - How did this TikTok campaign deliver yesterday? - Pull spend, clicks and conversions by ad group for the last 7 days. ### Which Smart+ materials are carrying the campaign Tool: `ads_get_smart_plus_material_report` A Smart+ campaign’s overview, or its performance broken down material by material — the answer to which videos the algorithm is actually spending on. Ask: - Which creatives in our Smart+ campaign get the most spend? - Break down this Smart+ campaign’s results by material. ### GMV Max results for your TikTok Shop Tool: `ads_get_gmv_max_report` GMV Max performance by store over a date range, for the metrics and dimensions you ask for. Ask: - How did our GMV Max campaigns perform last week? - Compare GMV Max results across our stores this month. ### How many people a targeting setup reaches Tool: `ads_estimate_audience_size` An audience-size estimate for ad-group targeting — locations, ages, gender, languages and interests — so two variants can be compared before either one spends. Ask: - How big is the audience for women 25–34 in the US interested in skincare? - Which of these two targeting setups reaches more people? ### Every campaign, as it stands on TikTok Tool: `ads_list_campaigns` The live campaign list with status and budget, straight from TikTok rather than from the last sync. Ask: - Which TikTok campaigns are running right now? - List our paused TikTok campaigns and their budgets. ### Also available - `ads_audit_ad_automation_inventory`: Audit every tracked automation setting against the live account - `ads_create_ad`: Draft a paused ad from a creative - `ads_download_change_history`: Download a finished change-log export - `ads_generate_ad_preview`: Preview how an ad renders - `ads_get_account_info`: Account status, currency, spend and billing facts - `ads_get_account_pages`: The Pages and identities the account can advertise as - `ads_get_ad`: One ad’s live status, creative and tracking - `ads_get_adset`: One ad set’s targeting, budget and bidding - `ads_get_campaign`: One campaign’s live settings and status - `ads_get_change_history_task`: Check on a change-log export - `ads_get_data_readiness`: Which date ranges have finished syncing - `ads_get_deploy_readiness`: Whether conversion tracking is ready for a conversion campaign - `ads_get_gmv_max_availability`: Whether a TikTok Shop can run GMV Max - `ads_get_gmv_max_campaign`: One GMV Max campaign - `ads_get_leads`: The leads a form or an ad collected - `ads_get_product_catalog_details`: One product catalog - `ads_get_product_feed_details`: One product feed - `ads_get_smart_plus_campaign`: One Smart+ campaign - `ads_list_ad_accounts`: The ad accounts your toolfare account can read - `ads_list_ad_rules`: Automated rules and what they do - `ads_list_ads`: The ads in an account, campaign or ad group - `ads_list_adsets`: Ad sets, with budget and targeting - `ads_list_conversion_actions`: The conversion actions the account tracks - `ads_list_custom_audiences`: Custom audiences - `ads_list_lead_forms`: Lead forms and their questions - `ads_list_pixels`: Pixels, and when each one last fired - `ads_list_product_catalogs`: Product catalogs - `ads_list_product_set_products`: The products in a product set - `ads_list_product_sets`: The product sets in a catalog - `ads_list_products`: The products in a catalog - `ads_list_saved_audiences`: Saved audiences - `ads_preview_automation_baseline`: Read an entity’s current automation settings - `ads_query_multi_dimension`: Performance broken down by several dimensions at once - `ads_search_geo_locations`: Look up location targeting keys - `ads_search_interests`: Search interest targeting - `ads_upload_images`: Upload images to the ad account library - `ads_upload_video`: Upload a video to the ad account library ## Price Free to read: it is your own account, so toolfare pays nobody for the data and charges nothing per read. No per-read charge to observe. Reads need no purchase. Like every toolfare call, they run only while your balance holds at least $0.003, and that is not spent. Balances and top-ups are in US dollars. Quotes and `--max-cost` count credits: 1,000 credits = $3 ($0.003 each). ## Use it when - Your TikTok CPA moved and you want the campaign, ad group or ad behind it. - You run Smart+ and want to know which materials the algorithm is spending on. - You sell through TikTok Shop and want GMV Max results by store. - You are choosing between targeting setups and want reach estimates first. ## Look elsewhere when - You want organic TikTok posts or creators. Your ad account only reports on your ads. - You want what competitors run on TikTok. That is an ad library, not your account. - You want to change a bid, pause an ad or create a campaign. Over MCP your AI can only propose new ads, and each one waits for your approval in toolfare. ## Limits - The reporting tool reads toolfare’s synced copy of the account. A freshly connected account backfills in stages, and TikTok has no live fallback while it does — an unsynced range is not zero spend. - Result-style metrics follow each ad group’s optimization goal, so they are not comparable across ad groups with different goals. - Change history is an export TikTok builds asynchronously; the connection can check on and download an export, but not start one.