report_integrated_get

Pass either `advertiser_id`/`advertiser_ids` or `bc_id`. When `report_type` is `BASIC` or `AUDIENCE`, pass `advertiser_id` or `advertiser_ids`; if both are provided, `advertiser_id` is ignored. When `report_type` is `PLAYABLE_MATERIAL`, `CATALOG`, or `TT_SHOP`, pass `advertiser_id`. When `report_type` is `BC`, pass `bc_id` instead. Advertiser ID.

Valid only when `report_type` is `BASIC` or `AUDIENCE`. You must pass either `advertiser_id` or `advertiser_ids`; if both are provided, `advertiser_id` is ignored. List of advertiser IDs, maximum size 5. When `advertiser_ids` is used, the response can include up to 20,000 IDs; cutoff is based on campaign, ad group, or ad creation time in descending order, and IDs may not be evenly distributed across advertisers. Returned `metrics` will include `currency`, `timezone`, and `advertiser_id`. Because advertisers can use different time zones, use `multi_adv_report_in_utc_time=true` to return all advertisers in UTC+0; otherwise data is returned in each advertiser's local time zone. Because advertisers can use different currencies, returned metric values use each advertiser's currency and are presented without a decimal point. To get total aggregated metrics across all advertiser IDs, enable `enable_total_metrics`; returned `total_metrics` will include `currency`, `timezone`, and `advertiser_id`, all set to `-`. If you use `advertiser_ids` but do not include any ID dimensions in `dimensions`, the response returns `0` for `currency`, `timezone`, and `advertiser_id`, and `-` for cost-related metrics such as `spend`. All advertisers in `advertiser_ids` must belong to the same TikTok for Business user or the request fails.

Pass either `advertiser_id`/`advertiser_ids` or `bc_id`. When `report_type` is `BC`, pass `bc_id`. When `report_type` is `BASIC` or `AUDIENCE`, use `advertiser_id` or `advertiser_ids` instead. When `report_type` is `PLAYABLE_MATERIAL`, `CATALOG`, or `TT_SHOP`, use `advertiser_id`. ID of a Business Center you have access to.

Data level to query. Required when `report_type` is `BASIC`, `AUDIENCE`, or `CATALOG`; not supported when `report_type=BC`. When `report_type=TT_SHOP`, only `AUCTION_ADVERTISER` and `AUCTION_CAMPAIGN` are allowed. `dimensions` must contain exactly one ID dimension that matches `data_level`: `AUCTION_ADVERTISER`→`advertiser_id`, `AUCTION_CAMPAIGN`→`campaign_id`, `AUCTION_ADGROUP`→`adgroup_id`, `AUCTION_AD`→`ad_id`. Do not include a second ID dimension. If you need parent object fields (e.g. `campaign_id`, `campaign_name`) while grouping by `ad_id`, keep `dimensions=["ad_id"]` and request those fields in `metrics`; do NOT add a second ID dimension. By default only undeleted objects are returned; to include deleted ones set the matching `campaign_status` / `adgroup_status` / `ad_status` filter to `STATUS_ALL` in `filtering`.

Grouping dimensions. Rules that fail the call if broken: 1. Use at most ONE ID dimension and match it to data_level: AUCTION_ADVERTISER→advertiser_id, AUCTION_CAMPAIGN→campaign_id, AUCTION_ADGROUP→adgroup_id, AUCTION_AD→ad_id. Never combine advertiser_id with campaign_id, or campaign_id with adgroup_id/ad_id; get parent IDs and names through `metrics` instead. 2. Name fields (campaign_name, adgroup_name, ad_name) are NOT dimensions; request them in `metrics`. 3. stat_time_day limits the date range to 30 days; stat_time_hour limits it to 1 day. For a longer range drop the time dimension or split into several calls. Example: ["campaign_id","stat_time_day"]. Other dimensions such as country_code depend on report_type. If dimensions contains only ID dimensions and there is no ads reporting within the time range, an empty list is returned.

Whether to return total aggregated values for the requested metrics. When enabled, aggregate data across all pages is returned, so you only need to specify this field on the first page request. Because of the 20,000 truncation limit, totals are provided for up to 20,000 IDs. Supported only for auction basic reports and GMV max ads reports. Valid only when `dimensions` contains one ID dimension and optionally `stat_time_day`, for example `["campaign_id"]` or `["campaign_id", "stat_time_day"]`. Not supported in the sandbox environment.

Required when `query_lifetime` is `false` or omitted. Query end date in `YYYY-MM-DD`, using the ad account time zone. When `query_lifetime=true`, this field is ignored. If `report_type` is not `BC` and `dimensions` does not include `stat_time_day`, the maximum range between `start_date` and `end_date` is 365 days. If `report_type` is not `BC` and `dimensions` includes `stat_time_day`, the maximum range is 30 days. If `report_type` is `BC`, the maximum range is 365 days.

Filtering conditions. Optional. Must be a JSON ARRAY of filter objects, never a plain object like {"campaign_ids":[...]}. Each object needs field_name, filter_type and filter_value. Example: [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"1875305651213777\"]"},{"field_name":"campaign_status","filter_type":"IN","filter_value":"[\"STATUS_ALL\"]"}] ID filters are plural: campaign_ids / adgroup_ids / ad_ids (not campaign_id). For IN, NOT_IN and CONTAIN_ANY_OF, filter_value is a JSON-array STRING such as "[\"id1\",\"id2\"]", not a bare ID. Metrics (spend, conversion) and names (campaign_name) cannot be filter fields: filter by IDs or status, then post-process the result. Status filters: campaign_status / adgroup_status / ad_status, e.g. STATUS_ALL to include deleted objects. Supported when report_type is BASIC, AUDIENCE, PLAYABLE_MATERIAL, CATALOG or BC; not supported for TT_SHOP. If you filter by country_code, also include country_code in `dimensions`.

Metrics to query. Names must match the API exactly; one unknown name fails the whole call. Do NOT use: conversions, cpa, roas, activate, landing_page_view, add_to_cart, onsite_add_to_cart, total_add_to_cart, purchase_value, video_views, budget. Common valid names: spend, impressions, clicks, ctr, cpc, cpm, reach, frequency, result, cost_per_result, conversion, cost_per_conversion, conversion_rate, real_time_conversion, complete_payment, cost_per_complete_payment, complete_payment_rate, complete_payment_roas, purchase, cost_per_purchase, purchase_rate, total_purchase_value, app_install, cost_per_app_install, registration, cost_per_registration, total_landing_page_view, total_pageview, checkout, add_billing, onsite_on_web_cart (add to cart), cost_per_onsite_on_web_cart, onsite_shopping, total_onsite_shopping_value, onsite_shopping_roas, on_web_order, total_on_web_order_value, video_play_actions, average_video_play, video_views_p25, video_views_p50, video_views_p75, video_views_p100, engaged_view, likes, comments, shares, follows, profile_visits. Attribute fields are requested here too, never in `dimensions` or `filtering`: campaign_name, adgroup_name, ad_name, objective_type, campaign_budget, and parent IDs (campaign_id at ad-group/ad level, adgroup_id at ad level). Do not put the ID that is already in `dimensions` into `metrics`. Default: ["spend","impressions"] for BASIC/AUDIENCE/PLAYABLE_MATERIAL/CATALOG; ["spend","billed_cost"] for TT_SHOP; for BC, all metrics supported by the selected dimensions. Currency metrics use the advertiser account currency.

Supported only when `advertiser_ids` is used. Default is `false`. If `true`, returned metrics for all advertisers use UTC+0. If `false`, returned metrics use each advertiser's local time zone.

Sorting field. All supported metrics except attribute metrics can be used for sorting. By default, results are not sorted.

Sorting order. Default is `DESC`.

Current page number. Default is `1`.

Pagination size. Range: 1-1000. Default is `10`.

Whether to request lifetime metrics. Supported only when `report_type` is `BASIC` or `PLAYABLE_MATERIAL`. Default is `false`. If `true`, `start_date` and `end_date` are ignored, and lifetime metrics use the same metric names as normal metrics. Breakdown by time, audience, or location code `country_code` is not supported for lifetime queries. Audience reports, DSA reports, Business Center reports, and GMV max ads reports do not support lifetime metrics.

Report type. When `service_type` is `AUCTION`, `BASIC`, `AUDIENCE`, `PLAYABLE_MATERIAL`, `CATALOG`, and `TT_SHOP` are supported. When `report_type` is `BC`, do not pass `service_type`. `BASIC` and `AUDIENCE` require `advertiser_id` or `advertiser_ids`; `PLAYABLE_MATERIAL`, `CATALOG`, and `TT_SHOP` use `advertiser_id`; `BC` uses `bc_id`.

Ad service type. Not supported when `report_type` is `BC`. Default is `AUCTION` when `report_type` is not `BC`. To retrieve TopView reporting data, use basic or audience reports and set the `buying_type` filter to `RESERVATION_TOP_VIEW`.

Required when `query_lifetime` is `false` or omitted. Query start date in `YYYY-MM-DD`, using the ad account time zone. When `query_lifetime=true`, this field is ignored. If `report_type` is not `BC` and `dimensions` does not include `stat_time_day`, the maximum range between `start_date` and `end_date` is 365 days. If `report_type` is not `BC` and `dimensions` includes `stat_time_day`, the maximum range is 30 days. If `report_type` is `BC`, the maximum range is 365 days.