report_task_create

Advertiser ID. Either `advertiser_id` or `advertiser_ids` must be set. If both `advertiser_id` and `advertiser_ids` are provided, `advertiser_id` is ignored.

List of advertiser IDs. Either `advertiser_id` or `advertiser_ids` must be set. If both are provided, `advertiser_id` is ignored. Max size: 5. Valid only when `report_type` is `BASIC` or `AUDIENCE`. All advertisers in `advertiser_ids` must belong to the same TikTok for Business user or an error occurs. If `start_date` and `end_date` are specified, data is pulled according to each ad account's timezone. When passing multiple advertiser IDs, you can specify up to two ID dimensions in `dimensions` (`advertiser_id` plus one other ID dimension). Many metrics do not support the `advertiser_id` dimension. It is recommended to include `currency` in `metrics` because ad accounts may use different currencies.

Report aggregation level. Required when `report_type` is `BASIC`, `AUDIENCE`, or `CATALOG`.

Grouping dimensions, for example `["campaign_id", "stat_time_day"]`. Supported dimensions vary by `report_type`. If `country_code` is used as a grouping filter in `filtering`, you must also include `country_code` in `dimensions`. If your `dimensions` contain more than `xx_id` and there is no ads reporting in the query time range, an empty list is returned. Dimension/metric combinations supported in synchronous reports may not be supported in asynchronous reports. The dimension `ad_id_v2` is available only when `report_type` is `BASIC`, `AUDIENCE`, or `CATALOG`; it cannot be used together with the dimension `ad_id` or the filter `ad_ids`. `ad_id_v2` can return ad-level data for Manual Ads, Smart+ Campaigns, and Upgraded Smart+ Ads.

Whether to translate the title row of the asynchronous report, including dimension and metric names. Default is `true`. Valid only when `report_type` is `BASIC` or `AUDIENCE`. If set to `false`, titles remain untranslated, for example `ad_id` instead of `AD ID`. Starting November 15th, 2024, translations of certain metrics in async report title rows will change. This does not affect metric field names. TikTok strongly recommends setting this field to `false` to avoid code dependencies on translations that may change over time.

Query end date in `YYYY-MM-DD` format, based on the ad account time zone. Required when `query_lifetime` is `false` or omitted. If `query_lifetime` is `true`, this field is ignored. Asynchronous reports have no time range limitations.

Custom download file name. Optional when `output_format` is `CSV_DOWNLOAD` or `XLSX_DOWNLOAD`. Maximum length is 255 characters. Must not contain any of these characters: `/`, `\t`, `\b`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `[`, `]`.

Filtering conditions. Supported filters vary by `service_type` and `data_level`. When you include `filtering`, each object in the list must include `field_name`, `filter_type`, and `filter_value` together. If you want to use `country_code` as a grouping filter, you must also include `country_code` in `dimensions`. In asynchronous mode, for basic, audience, and DSA reports, the only supported filter fields are `campaign_ids`, `adgroup_ids`, and `ad_ids`.

Metrics to query. Supported metrics vary by `report_type`. Default is `["spend", "impressions"]`. In async reports, UV metrics cannot be queried together with audience dimensions. Supported dimension/metric combinations may differ from synchronous reports.

Field to sort by. All supported metrics except attribute metrics support sorting. By default, no sorting is applied.

Sort order. Default is `DESC`.

Output format. Default is `CSV_STRING`. If `output_format` is `CSV_DOWNLOAD` or `XLSX_DOWNLOAD`, you may optionally provide `file_name`.

Whether to request lifetime metrics. Default is `false`. If `true`, `start_date` and `end_date` are ignored. Lifetime metric names are the same as the normal metric names. Breakdown by time, audience, or location code (`country_code`) is not supported for lifetime metrics. DSA reports do not support lifetime metrics. Audience reports do not support lifetime metrics at this time.

Report type. When `service_type` is `AUCTION`, supported values are `BASIC`, `AUDIENCE`, `PLAYABLE_MATERIAL`, and `CATALOG`. `data_level` is required when `report_type` is `BASIC`, `AUDIENCE`, or `CATALOG`. `advertiser_ids` is valid only when `report_type` is `BASIC` or `AUDIENCE`. `enable_report_title_translation` is valid only when `report_type` is `BASIC` or `AUDIENCE`. You can retrieve creative-level data for Upgraded Smart+ Ads when `report_type` is `BASIC`, `AUDIENCE`, or `CATALOG`.

Ad service type. Default is `AUCTION`. To retrieve TopView ad reporting data, use basic or audience reports and set the `buying_type` filter to `RESERVATION_TOP_VIEW`.

Query start date in `YYYY-MM-DD` format, based on the ad account time zone. Required when `query_lifetime` is `false` or omitted. If `query_lifetime` is `true`, this field is ignored. Asynchronous reports have no time range limitations.