TikTok Ads Report
  • 09 Aug 2024
  • 3 Minutes to read
  • Dark
    Light
  • PDF

TikTok Ads Report

  • Dark
    Light
  • PDF

Article summary

TikTok Ads Report API

API Documentation Link


Configuration Parameters

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.

When using an Incremental Key, this value will need to be the following: <<date_format(date_add({incval}, 'days', -1),'%Y-%m-%d')>>

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

When using an Incremental Key, this value will need to be the following: <<date_format(date_add(utcnow(), 'days', 1),'%Y-%m-%d')>>

  • $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.

Connector configuration

  • Base url: https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/
  • Method: GET
  • URL Parameters: advertiser_id={advertiser_id}&report_type={report_type}&data_level={data_level}&dimensions=[$dimensions]&metrics=[$metrics]&start_date={start_date}&end_date={end_date}&query_lifetime=false&page_size=200
  • Destination: tiktok_report_$report_description

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).

Authorization

  • Authorization API Key
  • Key: Access-Token
  • Value: {access_token}
  • Add to: Headers

Variables

Variable nameVariable value
advertiser_id$advertiser_id
report_type$report_type
data_level$data_level
start_date$start_date
end_date$end_date
access_token$access_token

Pagination

  • Enable: Checkbox.png
  • Get next page value: Static (integer to be incremented)
  • Start page: 1
  • Page step: 1
  • Use next page value: As a URL parameter value
  • URL/body key: page
  • Stop iterating when: Empty data

Advanced Settings

  • Data key: data.list
Primary Key

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}.

Incremental Key

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.

  • Nested Data:
    • Default Behavior: Flatten on parent table

Was this article helpful?