How to Integrate Retool with TikTok Ads

To access TikTok's Marketing API, you need a developer app registered in TikTok for Developers that has been granted access to your ad account. Navigate to developers.tiktok.com and sign in with your TikTok for Business account. Click Create App in the top right. Select Marketing API as the API type. Fill in the app name (e.g., Retool Integration), app description, and your company information. Under Scopes, enable the relevant scopes: at minimum, enable Reporting (for reading campaign metrics) and Ad Management Read (for reading campaign structure). Submit the app for review — basic marketing apps are typically approved within a few business days. Once approved, the app shows a status of Active. In the app detail page, copy the App ID and App Secret. To generate an access token, TikTok uses OAuth 2.0. For server-to-server integrations, use the OAuth authorization code flow: construct an authorization URL pointing to https://ads.tiktok.com/marketing_api/auth with your app_id, redirect_uri, and state parameters. After your TikTok for Business admin completes the OAuth flow and grants access, you receive an authorization code. Exchange this code at https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/ with your app_id, secret, and auth_code to receive an access_token and refresh_token. Store the access_token and note the advertiser_id returned in the OAuth response. TikTok access tokens expire after 24 hours but refresh tokens are valid for 365 days — implement a Retool Workflow to refresh the token daily using the refresh_token endpoint.

In Retool, navigate to the Resources tab in the left sidebar and click Add Resource. Select REST API from the list of resource types. Name the resource TikTok Marketing API. In the Base URL field, enter https://business-api.tiktok.com/open_api/v1.3 — this is the current stable API version endpoint. TikTok's Marketing API uses the version in the base URL path rather than as a parameter, so pin it here to control upgrade timing. In the Headers section, click Add Header. Set the header name to Access-Token and the value to {{ config.TIKTOK_ACCESS_TOKEN }}. This references a Retool configuration variable you will create for the access token. TikTok's Marketing API requires the Access-Token header (not the standard Authorization: Bearer format used by most APIs — this is a common source of 40001 authentication errors). To create the configuration variable: navigate to Settings → Configuration Variables in Retool. Click Add variable. Name it TIKTOK_ACCESS_TOKEN and paste your access token as the value. Enable the secret toggle so the token is restricted to resource configurations and never exposed to frontend JavaScript. Create a second configuration variable named TIKTOK_ADVERTISER_ID with your advertiser account ID — this will be referenced in query parameters rather than stored in the Resource itself, since many TikTok endpoints require it as a query parameter. Click Save on the Resource. Test the connection by creating a quick GET query to /advertiser/info/ with a URL parameter of advertiser_ids set to ["{{ config.TIKTOK_ADVERTISER_ID }}"] to confirm the token is valid.

TikTok's Reporting API uses a different pattern from most REST APIs: rather than querying /campaigns/insights, you POST a reporting request to /report/integrated/get/ with a structured JSON body specifying dimensions, metrics, and filters. Create a new query in Retool targeting your TikTok Marketing API resource. Set Method to GET (TikTok's integrated report endpoint accepts GET with query parameters, unlike the async report API). Set Path to /report/integrated/get/. In the URL Parameters section, add the following parameters. Add advertiser_id with value {{ retoolContext.configVars.TIKTOK_ADVERTISER_ID }}. Add report_type with value BASIC. Add dimensions with a JSON array value ["campaign_id","stat_time_day"] to get daily breakdown by campaign. Add metrics with a comma-separated string or JSON array of metric names: ["spend","impressions","clicks","ctr","cpm","cpc","reach","conversion","cost_per_conversion","video_play_actions","video_watched_2s","video_watched_6s"]. Add start_date and end_date parameters referencing your date picker component: start_date set to {{ formatDate(dateRangePicker.value[0], 'YYYY-MM-DD') }} and end_date set to {{ formatDate(dateRangePicker.value[1], 'YYYY-MM-DD') }}. Add data_level with value AUCTION_CAMPAIGN to get campaign-level data. Add page_size with value 200. Run the query — TikTok returns a data.list array with one object per dimension combination (one row per campaign per day). The response also includes a data.page_info object with total_number for pagination. Add a JavaScript transformer to the query in its Advanced tab to flatten the response and compute derived metrics like thumb-stop rate and video hold rate.

1// JavaScript transformer for TikTok Reporting API response
2// Flatten nested metrics and compute video performance ratios
3const rows = data.data?.list || [];
4
5return rows.map(row => {
6  const metrics = row.metrics || {};
7  const dimensions = row.dimensions || {};
8
9  const spend = parseFloat(metrics.spend || 0);
10  const impressions = parseInt(metrics.impressions || 0);
11  const clicks = parseInt(metrics.clicks || 0);
12  const conversions = parseInt(metrics.conversion || 0);
13  const videoPlays = parseInt(metrics.video_play_actions || 0);
14  const watched2s = parseInt(metrics.video_watched_2s || 0);
15  const watched6s = parseInt(metrics.video_watched_6s || 0);
16
17  return {
18    campaign_id: dimensions.campaign_id || '',
19    date: dimensions.stat_time_day || '',
20    spend: spend.toFixed(2),
21    spend_display: `$${spend.toFixed(2)}`,
22    impressions: impressions,
23    clicks: clicks,
24    ctr: metrics.ctr ? (parseFloat(metrics.ctr) * 100).toFixed(2) + '%' : '0%',
25    cpm: metrics.cpm ? `$${parseFloat(metrics.cpm).toFixed(2)}` : '$0',
26    cpc: metrics.cpc ? `$${parseFloat(metrics.cpc).toFixed(2)}` : '$0',
27    conversions: conversions,
28    cost_per_conversion: metrics.cost_per_conversion
29      ? `$${parseFloat(metrics.cost_per_conversion).toFixed(2)}`
30      : 'N/A',
31    thumb_stop_rate: impressions > 0
32      ? ((videoPlays / impressions) * 100).toFixed(1) + '%'
33      : '0%',
34    hold_rate: videoPlays > 0
35      ? ((watched6s / videoPlays) * 100).toFixed(1) + '%'
36      : '0%',
37    video_plays: videoPlays,
38    watched_2s: watched2s,
39    watched_6s: watched6s
40  };
41});

With campaign reporting data available, build the dashboard layout in Retool. Add a DateRangePicker component at the top of the canvas to control the reporting window — set a default value of last 7 days and constrain the maximum range to 90 days. Drag a Table component onto the canvas and bind its data to {{ getCampaignMetrics.data }}. The transformer already flattened the response, so each row maps directly to a Table row. Configure column headers with user-friendly labels: rename spend_display to Spend, thumb_stop_rate to Thumb-Stop Rate, hold_rate to 6s Hold Rate. Enable column sorting so buyers can rank campaigns by any metric. Add conditional formatting: highlight rows where cost_per_conversion exceeds a threshold value (reference a Number input for the target CPA). Drag a Chart component below the Table and set Chart type to Line. Bind data to the daily reporting query results. Set the X axis to the date dimension and add series for spend and conversions on separate Y axes to show spend trend alongside conversion volume. Add a second Chart as a grouped Bar chart comparing spend, impressions, and conversions across campaigns for the period — this gives a visual performance snapshot. Place Stat components at the top showing period totals: calculate these in a JavaScript query that sums the campaign metrics array. For creative-level analysis, create a second query at data_level AUCTION_AD with dimensions ["ad_id","ad_name"] and bind it to a second Table tab, enabling buyers to drill from campaign to individual creative performance.

1// JavaScript query: compute period totals for Stat components
2// Place this as a JavaScript query named 'computeTotals'
3const rows = getCampaignMetrics.data || [];
4
5const totalSpend = rows.reduce((sum, r) => sum + parseFloat(r.spend || 0), 0);
6const totalImpressions = rows.reduce((sum, r) => sum + (parseInt(r.impressions) || 0), 0);
7const totalClicks = rows.reduce((sum, r) => sum + (parseInt(r.clicks) || 0), 0);
8const totalConversions = rows.reduce((sum, r) => sum + (parseInt(r.conversions) || 0), 0);
9const blendedCPA = totalConversions > 0
10  ? (totalSpend / totalConversions).toFixed(2)
11  : 'N/A';
12
13return {
14  total_spend: `$${totalSpend.toFixed(2)}`,
15  total_impressions: totalImpressions.toLocaleString(),
16  total_conversions: totalConversions,
17  blended_cpa: blendedCPA !== 'N/A' ? `$${blendedCPA}` : 'N/A',
18  blended_ctr: totalImpressions > 0
19    ? ((totalClicks / totalImpressions) * 100).toFixed(2) + '%'
20    : '0%'
21};

TikTok Marketing API access tokens expire after 24 hours, which would break your Retool dashboard daily without automated refresh. Retool Workflows can handle this automatically. Navigate to Workflows in Retool and click Create workflow. Name it TikTok Token Refresh. Add a Schedule trigger set to run every 20 hours (before the 24-hour expiry window). In the workflow canvas, add a Resource Query block targeting your TikTok Marketing API resource. Configure the block: Method GET, Path /oauth2/refresh_token/. In the URL parameters, add app_id referencing your app ID (store as a configuration variable TIKTOK_APP_ID) and secret referencing your App Secret (store as TIKTOK_APP_SECRET), plus refresh_token referencing a configuration variable TIKTOK_REFRESH_TOKEN where you have stored your refresh token. Add a JavaScript Code block after the query block. In the code block, read the new access_token from the previous block's response: const newToken = refreshTokenQuery.data.data.access_token;. To update the Retool configuration variable programmatically, use the Retool API (available under Settings → Retool API) with a POST to /api/v2/environment_variables/TIKTOK_ACCESS_TOKEN. This creates a fully automated refresh loop. For complex multi-source advertising integrations involving TikTok, Meta, Google, and custom attribution logic across multiple Retool Resources, RapidDev's team can architect and build a comprehensive paid media operations platform.

1// JavaScript Code block in Retool Workflow
2// Reads new access token from refresh response and updates config variable
3const response = refreshTokenQuery.data;
4
5if (response.code !== 0) {
6  throw new Error(`Token refresh failed: ${response.message}`);
7}
8
9const newAccessToken = response.data.access_token;
10const newRefreshToken = response.data.refresh_token;
11
12// Log the refresh for debugging (check Workflow run logs)
13console.log('TikTok token refreshed successfully at', new Date().toISOString());
14console.log('New token expires in 24 hours');
15
16// Return token details for the workflow response block
17return {
18  success: true,
19  access_token: newAccessToken,
20  refresh_token: newRefreshToken,
21  refreshed_at: new Date().toISOString()
22};