Marketing Ad Platform APIs Overview

Bonsai ingests marketing performance and metadata from paid media platforms via each platform’s advertising API. While the exact available fields vary by channel, most platforms support a consistent reporting structure: account → campaign → ad group/ad set → ad/creative, with performance metrics provided by date and optional breakdowns.

Common data ingested across platforms:

Identifiers & hierarchy account_id, campaign_id, ad_group_id/ad_set_id, ad_id, creative_id

Time segmentation date / date_start, date_stop, hour

Core performance metrics impressions, clicks, spend/cost, ctr, cpc, cpm

Conversion metrics conversions, conversion_value/revenue, roas; breakdowns by action type (varies by platform)

Targeting/segment dimensions (optional) device, geo, audience, placements, demographic pivots, etc.

 

Google Ads

API documentation: This connector uses the Google Ads Big Query Data Transfer Service

Typical ingested entities:

• Customer/account
• Campaigns, ad groups, ads, keywords
• Search terms (when enabled/available)
• Assets (extensions), product listing groups (Shopping/PMax depending on access)

Typical fields ingested:

• customer_id, campaign_id, ad_group_id, ad_id, campaign.name
• impressions, clicks, cost_micros, ctr, average_cpc
• conversions, conversion_value, all_conversions
• segments.date, segments.device, segments.network
• gclid

Meta Ads (Facebook/Instagram)

API documentation: This connector uses Graph API version v23.0

Typical ingested entities:

• Ad Accounts
• Campaigns → Ad Sets → Ads
• Creatives
• Insights reporting at multiple levels

Typical fields ingested:

• account_id, campaign_id, adset_id, ad_id (+ names)
• impressions, clicks, spend, reach, frequency
• actions, action_values, attribution windows

Microsoft Advertising (Bing)

API documentation: This connector uses Microsoft Advertising API version 13.0

Typical ingested entities:

• Accounts
• Campaigns, ad groups, ads, keywords
• Performance reports (report “types” / column sets)

Typical fields ingested:

• AccountId, CampaignId, AdGroupId, AdId, KeywordId
• impressions, clicks, spend, CTR, average CPC
• conversions, revenue (depending on tracking setup)
• msclkid

TikTok Ads

API documentation: This connector uses TikTok Ads API v1.3

Typical ingested entities:

• Advertiser account
• Campaigns → Ad Groups → Ads
• Creative / video engagement metrics

Typical fields ingested:

• advertiser_id, campaign_id, adgroup_id, ad_id
• impressions, clicks, spend, ctr, cpc
• video engagement metrics (views, quartiles; platform dependent)

LinkedIn Ads

API documentation: This connector uses LinkedIn Marketing API version 202503

Typical ingested entities:

• Accounts
• Campaign groups / campaigns
• Creatives
• Ad analytics pivots (incl. professional demographics)

Typical fields ingested:

• account, campaign, creative identifiers
• impressions, clicks, spend, engagement metrics
• optional pivots: job title, company size, job function, seniority (privacy thresholds may apply)

Amazon Ads

API documentation: This connector uses Amazon Ads API v1

Typical ingested entities:

• Sponsored Products / Sponsored Brands / Sponsored Display reporting
• Campaigns, ad groups, ads, keywords/targets
• DSP reporting (if applicable)

Typical fields ingested:

• campaign/ad group/ad IDs (varies by ad product type)
• impressions, clicks, cost
• attributed purchases, sales, units, ROAS (varies by report type)

Pinterest Ads

API documentation: This connector uses Pinterest Ads API v5

Typical ingested entities:

• Ad accounts
• Campaigns, ad groups, ads (Pins)
• Analytics reporting endpoints

Typical fields ingested:

• ad_account_id, campaign_id, ad_group_id, ad_id
• impressions, clicks, spend
• conversion metrics depending on configured tag/events