TikTok Ads Report

Any instance where an entry in the below configuration has a leading $ represents a parameter that needs to be replaced with a static value.

Parameters in this document:

• $access_token - The Access Token will provide access to the TikTok Ads Report API. Before going through Authentication steps, you must first get Authorization from the advertiser, which can be done by following the steps found here. Documentation on how to then generate the Access Token through Authentication can be found here. This step may require Panoply's assistance, so please reach out with any questions to our Support Team and we'd be happy to assist.
• $report_type - The Report Type represents the TikTok Ads report that is being ingested. The list of available Report Type values can be found here. Once a report type is chosen, this parameter should be one of the following values: BASIC, AUDIENCE, PLAYABLE_MATERIAL, CATALOG, or BC.
• $data_level - This parameter represents the level at which data is aggregated in the report. For information about which values are acceptable for a given Report Type, see documentation here under the section labeled Data level.
• $advertiser_id - In your TikTok business account, you can find this parameter value in the Users > Members section, under the Advertiser account.
• $metrics - The metrics (spend, clicks, etc.) that you would like to include in your report from the TikTok API. The list of available metrics will vary by Report Type, so visit this location to view the different Report Types, and then follow the For details link to see the supported metrics. When entering a value for this parameter, if you would like to use multiple metrics, they should be entered as a comma separated list (e.g. "campaign_name","adgroup_name","ad_name","ad_text").
• $dimensions - The dimensions (campaign_id, country_code, etc.) that you would like to include in your report from the TikTok API. The list of available dimensions will vary by Report Type, so visit this location to view the different Report Types, and then follow the For details link to see the supported dimensions. When entering a value for this parameter, if you would like to use multiple dimensions, they should be entered as a comma separated list (e.g. "adid","stattime_day").
• $start_date - The Start Date of the data that you would like to receive, given in yyyy-mm-DD format.

• $end_date - The End Date of the data that you would like to receive, given in yyyy-mm-DD format.

• $report_description - The Report Description will be used in the Destination Table naming, and should be used to accurately describe the report you are ingesting. For example, if the report you've created is primarily used for gathering a variety of metrics grouped by country, you may utilize this parameter as metrics_by_country, thus making the full Destination Table name tiktok_report_metrics_by_country.

Destination table naming convention is ultimately up to you as the data owner. Naming the table such that it accurately portrays the purpose of the report would be Panoply's recommendation (e.g. tiktok_report_clicks_by_country).

The Primary Key will be an aggregation of the list of dimensions selected in the report, in the following structure: {dimensions_<dimension_1>}-{dimensions_<dimension_2>}-...-{dimensions_<dimension_n>}. For example, if the dimensions selected are campaign_id and stat_time_day, then the Primary Key will be {dimensions_campaign_id}-{dimensions_stat_time_day}.

Similar to the Primary Key, the Incremental Key will depend on the report structure, and will likely be any field that represents a date value that is being ingested as a dimension. The structure of this field will be dimensions.<fieldname>. For example, if the date value in your report is stat_time_day, the Incremental Key will be dimensions.stat_time_day. Please note that when entering a column value to the Incremental Key feature, you will need to use the following format: YYYY-MM-DD 00:00:00.