View as Markdown
TikTok Ads Manager icon

TikTok Ads Manager ACTION

Get Report

Run a synchronous report to retrieve performance metrics for campaigns, ad groups, or ads. report_type is required. advertiser_id is required for BASIC, AUDIENCE, PLAYABLE_MATERIAL, CATALOG, and TT_SHOP reports; use bc_id for BC reports. data_level is required for BASIC, AUDIENCE, and CATALOG reports. start_date and end_date are required unless query_lifetime is true. dimensions must include an entity ID dimension for the chosen level (campaign_id, adgroup_id, or ad_id) plus a time dimension (stat_time_day or stat_time_hour). Common metrics: impressions, clicks, spend, cpc, cpm, ctr, reach, conversion, cost_per_conversion. See the documentation
  • Action
  • Read only
  • OAuth
  • SDK
  • MCP

IMPLEMENTATION

Call this tool

Connect a user's TikTok Ads Manager account once, then configure and run Get Report from your backend or agent.

import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "tiktok_ads_manager-get-report",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    tiktok_ads_manager: { authProvisionId: "apn_xxxxxxx" },
    advertiserId: "Advertiser ID",
    bcId: "Business Center ID",
  },
})

console.log(result)

SCHEMA

Inputs

Pipedream supplies the connected account. Your application provides the operation-specific values below. Dynamic inputs are resolved against that user's account.

Get Report inputs
Property Type Description
advertiserId Advertiser ID string
Required for BASIC, AUDIENCE, PLAYABLE_MATERIAL, CATALOG, and TT_SHOP reports. Not used for BC reports — use bc_id instead.
Optional
bcId Business Center ID string
Required when report_type is BC. ID of the Business Center to report on. Use /bc/get/ to find your Business Center IDs.
Optional
reportType Report Type string
BASIC is the standard performance report. AUDIENCE breaks down by audience attributes. BC reports on a Business Center (requires bc_id).
Required
dataLevel Data Level string
Granularity of the report. Required for BASIC, AUDIENCE, and CATALOG reports. AUCTION_CAMPAIGN = campaign level, AUCTION_ADGROUP = ad group level, AUCTION_AD = ad level, AUCTION_ADVERTISER = advertiser level.
Optional
dimensions Dimensions string[]
Required. Dimensions to group by. Include the entity ID for the chosen data_level (campaign_id, adgroup_id, or ad_id) plus a time dimension (stat_time_day). Example: ["campaign_id", "stat_time_day"].
Required
metrics Metrics string[]
Metrics to return. Example: ["impressions", "clicks", "spend", "cpc", "ctr"].
Optional
startDate Start Date string
Report start date in YYYY-MM-DD format. Required unless query_lifetime is true. Max range is 30 days when stat_time_day is in dimensions, 365 days otherwise.
Optional
endDate End Date string
Report end date in YYYY-MM-DD format. Required unless query_lifetime is true.
Optional
queryLifetime Query Lifetime boolean
If true, returns lifetime metrics and ignores start_date/end_date. Only supported for BASIC and PLAYABLE_MATERIAL report types.
Optional
serviceType Service Type string
Ad service type. Not used for BC reports. Default is AUCTION.
Optional
filtering Filtering string
JSON array of filter objects, each with field_name, filter_type, and filter_value. Example: [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}].
Optional
orderField Order Field string
Metric to sort results by. All supported metrics (excluding attribute metrics) can be used.
Optional
orderType Order Type string
Sort direction. Default is DESC.
Optional
page Page integer
Page number for paginated results. Starts at 1.
Optional
pageSize Page Size integer
Number of results per page. Default: 10, max: 1000.
Optional

REFERENCE

Tool details

Behavior hints are published with the component in the Pipedream registry and surface as MCP tool annotations, so an agent can reason about a tool before it calls it.

Registry key
tiktok_ads_manager-get-report
Version
0.0.2
App
TikTok Ads Manager
Authentication
OAuth
Read-only
Yes
Destructive
No
Open world
Yes