TikTok Ads is the advertising platform of TikTok, the leading short-form video app with 1B+ monthly active users. Through the TikTok Marketing (Business) API, advertisers manage ad campaigns, retrieve performance reports, access audience segments, and work with creative assets. Its hierarchy — Business Center, Advertiser, Campaign, Ad Group, Ad — gives data teams precise control for reporting and BI integration.
Power end-to-end data operations for your TikTok Ads API with Nexla. Our bi-directional TikTok Ads connector is purpose-built for TikTok Ads, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to TikTok Ads or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your TikTok Ads workflows fast, secure, and fully governed.
Features
Type: API
SourceDestination
Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
Request optimization with intelligent batching, retry, and caching to minimize API calls and costs
The TikTok Ads connector uses OAuth 2.0 (3-legged authorization flow) to authenticate with the TikTok Marketing API. Before creating a credential in Nexla, you must register a developer application in the TikTok developer portal to obtain a Client ID and Client Secret.
Register a TikTok for Business Developer Application
To obtain the OAuth credentials required by Nexla, create an application in the TikTok developer portal and request access to the Marketing API.
Sign in to the TikTok Developer Portal using your TikTok for Business account credentials. If your organization does not yet have a TikTok for Business account, create one at business.tiktok.com before proceeding.
Navigate to Manage Apps and click Connect a new app.
Fill in the required application details:
App Name: Enter a descriptive name for the integration (for example, "Nexla Data Integration").
App Icon: Upload an icon for your application.
Category: Select the category that most closely matches your use case.
Under Products, select Marketing API to request access to the TikTok Business API endpoints that Nexla will use.
Under Permissions / Scopes, select the following scopes, which correspond to the data that Nexla will access:
ad_management_basic — Required to read campaign, ad group, and ad data.
ad_management_audience — Required to read custom audience and pixel data.
ad_management_reporting — Required to retrieve performance reports.
Enter a valid Redirect URI for your integration. For Nexla-managed OAuth, use the redirect URI provided in the Nexla credential overlay.
Click Submit to save the application.
After the application is created, navigate to the app's detail page. Copy and securely store the App ID (Client ID) and App Secret (Client Secret) shown on this page.
New applications start in Sandbox Mode, which allows you to test the OAuth flow and API calls against limited data before submitting for production review. For production use with live advertiser data, submit the application for TikTok's review through the developer portal. The review process evaluates your OAuth implementation, data handling practices, and use-case appropriateness. Additional information is available in the TikTok Business API documentation.
Each TikTok Ads data source request requires an Advertiser ID that identifies the specific ad account to query. The Advertiser ID is a 19-digit number assigned to each TikTok Ads Manager account.
The Advertiser ID appears in the browser URL as the value of the aadvid parameter — for example: https://ads.tiktok.com/i18n/dashboard?aadvid=7012345678901234567.
Copy this value. You will need to enter it when configuring individual data source endpoints in Nexla.
If you manage multiple ad accounts through a Business Center, each account has its own unique Advertiser ID. When configuring Nexla data sources, you specify the Advertiser ID for the account you wish to pull data from. A list of advertiser IDs accessible to the authorized app is also returned as part of the OAuth token exchange response.
After selecting the data source type, click the Add Credential tile to open the Add New Credential overlay, and enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.
The TikTok Ads connector authenticates using OAuth 2.0 with a 3-legged authorization flow. In this flow, Nexla redirects you to TikTok's authorization page, where you grant the application permission to access your advertiser accounts. After authorization, TikTok issues an access token and a refresh token that Nexla uses for all subsequent API calls. The access token is short-lived and Nexla automatically refreshes it using the refresh token, which is valid for approximately one year.
Enter the App ID (Client ID) obtained from the TikTok developer portal in the Client ID field. This value identifies the registered TikTok application that Nexla will use to make API calls on your behalf.
Enter the App Secret (Client Secret) obtained from the TikTok developer portal in the Client Secret field. This value is used to securely exchange the authorization code for an access token and refresh token.
Important
The Client Secret is sensitive. Treat it like a password — do not share it publicly or commit it to source control. If you believe it has been exposed, regenerate it immediately in the TikTok developer portal under Manage Apps > your app > App Secret.
Click the Authorize button in the credential overlay. Nexla will redirect you to TikTok's authorization page.
On the TikTok authorization page, sign in with the TikTok for Business account that has access to the advertiser accounts you wish to connect, and grant the requested permissions (ad_management_basic, ad_management_audience, and ad_management_reporting).
After authorization is complete, TikTok will redirect back to Nexla with an authorization code. Nexla automatically exchanges this code for an access token and refresh token, completing the credential setup.
TikTok access tokens expire after 24 hours and are automatically refreshed by Nexla using the refresh token. If the refresh token itself expires (after approximately one year), you will need to re-authorize the credential by repeating the OAuth flow above.
Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source creation and can be selected for use with a new data source.
The TikTok Ads connector enables you to ingest advertising data from the TikTok Marketing API — including campaign structures, ad group and ad details, performance reports, audience segments, and creative assets — directly into Nexla. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the TikTok Ads connector tile, then select the credential that will be used to connect to the TikTok Ads account, and click Next; or, create a new TikTok Ads credential for use in this flow.
Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common TikTok Marketing API endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.
Advertiser Info
Retrieves account information and metadata for a TikTok Ads advertiser account. Use this endpoint to pull account-level details such as account name, status, currency, timezone, and associated business information. This is useful for account auditing, reporting context, and validating which accounts are accessible via your credentials.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field. This is the 19-digit numeric identifier for the ad account you wish to query. You can find this value in the TikTok Ads Manager URL as the aadvid parameter (for example, 7012345678901234567).
If you manage multiple advertiser accounts, each account has a distinct Advertiser ID. Create a separate data source for each account you wish to ingest data from.
Campaigns
Retrieves all campaigns for a TikTok Ads advertiser account, including campaign objectives, budget settings, status, and optimization goals. Use this endpoint to monitor your campaign portfolio, track budget allocations, or feed campaign metadata into a data warehouse for analysis alongside performance data.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field. This is the 19-digit identifier for the ad account whose campaigns you want to retrieve.
This endpoint uses paginated retrieval, automatically fetching all campaigns across multiple pages. Up to 1,000 records are fetched per page.
Campaign data includes fields such as campaign_id, campaign_name, objective_type, budget, budget_mode, and status. Additional details are available in the TikTok Campaign API documentation.
Ad Groups
Retrieves ad group (also called ad set) data for a TikTok Ads advertiser account, including targeting settings, bid strategy, placement, and optimization objectives. Ad groups sit between campaigns and individual ads in TikTok's account hierarchy and contain the audience targeting and delivery settings that govern how ads are shown.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field. This is the 19-digit identifier for the ad account whose ad groups you want to retrieve.
This endpoint uses paginated retrieval, automatically fetching all ad groups across multiple pages. Up to 1,000 records are fetched per page.
Ad group data includes fields such as adgroup_id, adgroup_name, campaign_id, bid_type, budget, targeting, and status. Additional details are available in the TikTok Ad Group API documentation.
Ads
Retrieves individual ad creative details and configurations for a TikTok Ads advertiser account. Use this endpoint to pull ad-level data such as ad names, creative formats, call-to-action text, landing page URLs, and status. This is useful for creative auditing, A/B test analysis, and building a creative performance dashboard.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field. This is the 19-digit identifier for the ad account whose ads you want to retrieve.
This endpoint uses paginated retrieval, automatically fetching all ads across multiple pages. Up to 1,000 records are fetched per page.
Ad data includes fields such as ad_id, ad_name, adgroup_id, creative_type, call_to_action, landing_page_url, and status. Additional details are available in the TikTok Ad API documentation.
Ad Performance Report
Retrieves daily performance metrics at the individual ad level. Metrics include spend, impressions, clicks, click-through rate (CTR), cost-per-click (CPC), CPM, conversions, cost-per-conversion, and conversion rate. Use this endpoint to build ad-level performance dashboards, track creative effectiveness, and analyze return on ad spend over a specified date range.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field. This is the 19-digit identifier for the ad account whose ad performance data you want to retrieve.
Enter the report start date in the Start Date field, using the format YYYY-MM-DD (for example, 2024-01-01). The default value is {now-30}, which resolves to 30 days before the current date.
Enter the report end date in the End Date field, using the format YYYY-MM-DD (for example, 2024-01-31). The default value is {now}, which resolves to the current date.
This endpoint uses paginated retrieval, automatically fetching data across multiple pages. Up to 1,000 records are fetched per page.
TikTok's reporting API requires that the date range does not exceed 180 days in a single request. For longer historical pulls, consider splitting the date range across multiple data sources. Additional details are available in the TikTok Reporting API documentation.
Ad Group Performance Report
Retrieves daily performance metrics aggregated at the ad group level. Metrics include spend, impressions, clicks, CTR, CPC, CPM, conversions, cost-per-conversion, and conversion rate. Use this endpoint to compare targeting strategy effectiveness, evaluate bid performance across ad groups, and roll up data for campaign-level analysis.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
Enter the report start date in the Start Date field using the format YYYY-MM-DD. The default value is {now-30}.
Enter the report end date in the End Date field using the format YYYY-MM-DD. The default value is {now}.
This endpoint uses paginated retrieval and automatically fetches data across all pages. Up to 1,000 records are fetched per page.
Retrieves daily performance metrics aggregated at the campaign level. Metrics include spend, impressions, clicks, CTR, CPC, CPM, conversions, cost-per-conversion, and conversion rate. Use this endpoint to track high-level campaign performance, compare budget efficiency across campaigns, and produce executive-level advertising reports.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
Enter the report start date in the Start Date field using the format YYYY-MM-DD. The default value is {now-30}.
Enter the report end date in the End Date field using the format YYYY-MM-DD. The default value is {now}.
This endpoint uses paginated retrieval and automatically fetches data across all pages. Up to 1,000 records are fetched per page.
Retrieves ad performance metrics broken down by audience age group and gender. Metrics include spend, impressions, clicks, and conversions. Use this endpoint to understand which demographic segments are responding to your ads, enabling more informed targeting and creative decisions.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
Enter the report start date in the Start Date field using the format YYYY-MM-DD. The default value is {now-30}.
Enter the report end date in the End Date field using the format YYYY-MM-DD. The default value is {now}.
This endpoint uses paginated retrieval and automatically fetches data across all pages. Up to 1,000 records are fetched per page.
This report uses TikTok's Audience Report type and segments data by ad_id, stat_time_day, gender, and age dimensions. Additional details are available in the TikTok Audience Report documentation.
Audience Report by Country
Retrieves ad performance metrics broken down by country. Metrics include spend, impressions, clicks, and conversions. Use this endpoint to assess geographic performance, identify high-performing markets, and optimize country-level targeting and budget allocation.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
Enter the report start date in the Start Date field using the format YYYY-MM-DD. The default value is {now-30}.
Enter the report end date in the End Date field using the format YYYY-MM-DD. The default value is {now}.
This endpoint uses paginated retrieval and automatically fetches data across all pages. Up to 1,000 records are fetched per page.
This report segments data by ad_id, stat_time_day, and country_code dimensions. Additional details are available in the TikTok Audience Report documentation.
Audience Report by Platform
Retrieves ad performance metrics broken down by platform (for example, iOS or Android). Metrics include spend, impressions, clicks, and conversions. Use this endpoint to compare performance across device platforms and tailor creative or bidding strategies accordingly.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
Enter the report start date in the Start Date field using the format YYYY-MM-DD. The default value is {now-30}.
Enter the report end date in the End Date field using the format YYYY-MM-DD. The default value is {now}.
This endpoint uses paginated retrieval and automatically fetches data across all pages. Up to 1,000 records are fetched per page.
This report segments data by ad_id, stat_time_day, and platform dimensions. Additional details are available in the TikTok Audience Report documentation.
Custom Audiences
Retrieves the list of custom audience segments and lookalike audiences defined in a TikTok Ads advertiser account. Custom audiences are targeting segments built from first-party data such as customer lists, website visitors (via TikTok Pixel), or app activity. Use this endpoint to inventory your audience assets, audit audience configurations, or sync audience metadata with external data platforms.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 100 records are fetched per page.
Custom audience data includes fields such as audience_id, name, audience_type, size, and status. Additional details are available in the TikTok Custom Audience API documentation.
Pixels
Retrieves tracking pixel configurations and metadata for a TikTok Ads advertiser account. TikTok Pixels are JavaScript tags placed on websites to track visitor actions and feed conversion data back to TikTok Ads for attribution and retargeting. Use this endpoint to audit pixel deployments, verify pixel configurations, and correlate pixel events with campaign performance.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 100 records are fetched per page.
Pixel data includes fields such as pixel_id, name, status, and pixel configuration details. Additional details are available in the TikTok Pixel API documentation.
Video Creatives
Retrieves video creative assets and metadata from the TikTok Ads creative library for an advertiser account. Use this endpoint to inventory video creatives, retrieve video IDs for use in ad creation, review video durations and formats, or audit the creative library for compliance and performance analysis.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 100 records are fetched per page.
Video creative data includes fields such as video_id, file_name, duration, size, and cover_url. Additional details are available in the TikTok Video Creative API documentation.
Image Creatives
Retrieves image creative assets and metadata from the TikTok Ads creative library for an advertiser account. Use this endpoint to inventory image creatives, retrieve image IDs for use in ad creation, or audit image assets for compliance.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 100 records are fetched per page.
Image creative data includes fields such as image_id, file_name, size, width, height, and url. Additional details are available in the TikTok Image Creative API documentation.
Smart Plus Ads
Retrieves Smart Plus ad data, including automation settings and configurations. Smart Plus is TikTok's AI-powered ad automation solution that optimizes creative, targeting, and bidding automatically. Use this endpoint to monitor Smart Plus ad configurations and track automated campaign performance.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 1,000 records are fetched per page.
Retrieves Smart Plus ad creative materials and assets for an advertiser account. Use this endpoint to access the creative components associated with Smart Plus automated campaigns, including AI-generated variations and assets submitted for automation.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 1,000 records are fetched per page.
Retrieves Smart Plus ad media files and creative components for an advertiser account. This endpoint provides access to the individual media assets that make up Smart Plus automated ads.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 1,000 records are fetched per page.
Retrieves Smart Plus ad optimization suggestions and recommendations generated by TikTok's AI for an advertiser account. Use this endpoint to programmatically access and act on TikTok's automated recommendations for improving Smart Plus campaign performance.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
This endpoint uses paginated retrieval. Up to 1,000 records are fetched per page.
Retrieves daily campaign performance metrics segmented by country. Metrics include spend, impressions, clicks, and conversions, broken down by campaign and country code. Use this endpoint to analyze how campaigns perform across different geographic markets on a daily basis, enabling country-level budget optimization and cross-market reporting.
Enter your TikTok Ads advertiser account ID in the Advertiser ID field.
Enter the report start date in the Start Date field using the format YYYY-MM-DD. The default value is {now-30}.
Enter the report end date in the End Date field using the format YYYY-MM-DD. The default value is {now}.
This endpoint uses paginated retrieval and automatically fetches data across all pages. Up to 1,000 records are fetched per page.
This report segments data by campaign_id, stat_time_day, and country_code dimensions. Additional details are available in the TikTok Reporting API documentation.
Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.
TikTok Ads data sources can also be manually configured to ingest data from any valid TikTok Marketing API endpoint not covered by the pre-built templates. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.
All TikTok Marketing API endpoints follow the base URL pattern https://business-api.tiktok.com/open_api/{'{version}'}/ (the current API version is v1.3). For endpoints that return a list of objects, the path to data is $.data.list[*]; for endpoints that return a single object, use $.data. The total record count and pagination metadata are available at $.data.page_info.total_number, outside the data path. Reporting endpoints require start_date and end_date query parameters in YYYY-MM-DD format, and the date range cannot exceed 180 days per request. You do not need to include the Access-Token authorization header — Nexla adds this automatically using your saved TikTok Ads credential.
Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new TikTok Ads data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.
