# 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](https://docs.cloud.google.com/bigquery/docs/google-ads-transfer?_gl=1*10mulal*_ga*NjIyMTk5MjkwLjE3NDI2MTYxNDk.*_ga_WH2QY8WWF5*czE3Njg0MzAwODckbzEzMyRnMSR0MTc2ODQzMDA5OCRqNDkkbDAkaDA.#console)

**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](https://developers.facebook.com/docs/graph-api/changelog/version23.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](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13)

**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](https://business-api.tiktok.com/portal/docs?id=1740579480076290)

**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](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/ads-overview?view=li-lms-2025-03)

**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](https://advertising.amazon.com/API/docs/en-us/reference/api-overview?utm_source=chatgpt.com)

**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](https://developers.pinterest.com/docs/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