{"openapi":"3.0.0","paths":{"/api/v1/usage":{"get":{"operationId":"getUsage","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}}},"summary":"Current credits, rate limit, plan, and tracked-advertiser count","tags":["Account"]}},"/api/v1/explore/meta/ads":{"get":{"operationId":"listMetaAds","parameters":[{"name":"advertiser_id","required":false,"in":"query","description":"Filter to one advertiser (id token).","schema":{"type":"string"}},{"name":"query","required":false,"in":"query","description":"Free-text search across creative text.","schema":{"type":"string"}},{"name":"active","required":false,"in":"query","description":"true | false — active vs ended.","schema":{"type":"string"}},{"name":"started_after","required":false,"in":"query","description":"Created on/after (ISO 8601).","schema":{"type":"string"}},{"name":"updated_after","required":false,"in":"query","description":"Ingested on/after (ISO 8601).","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["video","image"]}},{"name":"sort","required":false,"in":"query","schema":{"type":"string","enum":["newest","oldest","reach_desc"]}},{"name":"cursor","required":false,"in":"query","description":"Opaque pagination cursor.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":25,"default":25,"type":"number"}},{"name":"ids","required":false,"in":"query","description":"Batch-hydrate ad id tokens (comma-separated, max 25). When set, filters/pagination are ignored.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MetaAdSummary"}}}}}},"security":[{"oauth":[]}],"summary":"List (or batch-hydrate) Meta ads from your tracked advertisers","tags":["Explore · Meta Ads"]}},"/api/v1/explore/meta/ads/reach":{"get":{"operationId":"batchMetaAdReach","parameters":[{"name":"from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"ids","required":false,"in":"query","description":"Ad id tokens (comma-separated, max 25).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MetaReachTimeline"}}}}}},"security":[{"oauth":[]}],"summary":"Reach timeseries for multiple Meta ads (sync path)","tags":["Explore · Meta Ads"]}},"/api/v1/explore/meta/ads/{id_token}":{"get":{"operationId":"getMetaAd","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated heavy includes: full_targeting.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaAd"}}}}},"security":[{"oauth":[]}],"summary":"Get one Meta ad","tags":["Explore · Meta Ads"]}},"/api/v1/explore/meta/ads/{id_token}/reach":{"get":{"operationId":"getMetaAdReach","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaReachTimeline"}}}}},"security":[{"oauth":[]}],"summary":"Daily reach timeseries for one Meta ad","tags":["Explore · Meta Ads"]}},"/api/v1/explore/tiktok/ads":{"get":{"operationId":"listTiktokAds","parameters":[{"name":"advertiser_id","required":false,"in":"query","description":"Filter to one advertiser (id token).","schema":{"type":"string"}},{"name":"query","required":false,"in":"query","description":"Free-text search across creative text.","schema":{"type":"string"}},{"name":"active","required":false,"in":"query","description":"true | false — active vs ended.","schema":{"type":"string"}},{"name":"started_after","required":false,"in":"query","description":"First shown on/after (ISO 8601).","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["video","image"]}},{"name":"sort","required":false,"in":"query","schema":{"type":"string","enum":["newest","oldest","reach_desc"]}},{"name":"cursor","required":false,"in":"query","description":"Opaque pagination cursor.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":25,"default":25,"type":"number"}},{"name":"ids","required":false,"in":"query","description":"Batch-hydrate ad id tokens (comma-separated, max 25). When set, filters/pagination are ignored.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TiktokAdSummary"}}}}}},"security":[{"oauth":[]}],"summary":"List (or batch-hydrate) TikTok ads from your tracked advertisers","tags":["Explore · TikTok Ads"]}},"/api/v1/explore/tiktok/ads/reach":{"get":{"operationId":"batchTiktokAdReach","parameters":[{"name":"from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"ids","required":false,"in":"query","description":"Ad id tokens (comma-separated, max 25).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TiktokReachTimeline"}}}}}},"security":[{"oauth":[]}],"summary":"Reach timeseries for multiple TikTok ads (sync path)","tags":["Explore · TikTok Ads"]}},"/api/v1/explore/tiktok/ads/{id_token}":{"get":{"operationId":"getTiktokAd","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated heavy includes: full_targeting, transcript.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokAd"}}}}},"security":[{"oauth":[]}],"summary":"Get one TikTok ad","tags":["Explore · TikTok Ads"]}},"/api/v1/explore/tiktok/ads/{id_token}/reach":{"get":{"operationId":"getTiktokAdReach","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokReachTimeline"}}}}},"security":[{"oauth":[]}],"summary":"Daily reach timeseries for one TikTok ad","tags":["Explore · TikTok Ads"]}},"/api/v1/explore/tiktok/ads/{id_token}/snapshots":{"get":{"operationId":"listTiktokAdSnapshots","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque pagination cursor.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":25,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TiktokAdSnapshot"}}}}}},"security":[{"oauth":[]}],"summary":"List point-in-time captures of one TikTok ad","tags":["Explore · TikTok Ads"]}},"/api/v1/explore/tiktok/ads/{id_token}/snapshots/{snapshot_uuid}":{"get":{"operationId":"getTiktokAdAtSnapshot","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"snapshot_uuid","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokAd"}}}}},"security":[{"oauth":[]}],"summary":"Get a TikTok ad as captured at a snapshot","tags":["Explore · TikTok Ads"]}},"/api/v1/explore/google/ads":{"get":{"operationId":"listGoogleAds","parameters":[{"name":"advertiser_id","required":false,"in":"query","description":"Filter to one advertiser (id token).","schema":{"type":"string"}},{"name":"query","required":false,"in":"query","description":"Free-text search across headline and description.","schema":{"type":"string"}},{"name":"active","required":false,"in":"query","description":"true | false — active vs ended.","schema":{"type":"string"}},{"name":"started_after","required":false,"in":"query","description":"First shown on/after (ISO 8601).","schema":{"type":"string"}},{"name":"updated_after","required":false,"in":"query","description":"Last shown on/after (ISO 8601).","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["video","image","text"]}},{"name":"sort","required":false,"in":"query","schema":{"type":"string","enum":["newest","oldest","reach_desc"]}},{"name":"cursor","required":false,"in":"query","description":"Opaque pagination cursor.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":25,"default":25,"type":"number"}},{"name":"ids","required":false,"in":"query","description":"Batch-hydrate ad id tokens (comma-separated, max 25). When set, filters/pagination are ignored.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAdSummary"}}}}}},"security":[{"oauth":[]}],"summary":"List (or batch-hydrate) Google ads from your tracked advertisers","tags":["Explore · Google Ads"]}},"/api/v1/explore/google/ads/{id_token}":{"get":{"operationId":"getGoogleAd","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated heavy includes: full_targeting.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAd"}}}}},"security":[{"oauth":[]}],"summary":"Get one Google ad","tags":["Explore · Google Ads"]}},"/api/v1/explore/linkedin/ads":{"get":{"operationId":"listLinkedinAds","parameters":[{"name":"advertiser_id","required":false,"in":"query","description":"Filter to one advertiser (id token).","schema":{"type":"string"}},{"name":"query","required":false,"in":"query","description":"Free-text search across headline and commentary.","schema":{"type":"string"}},{"name":"active","required":false,"in":"query","description":"true | false — active vs ended.","schema":{"type":"string"}},{"name":"started_after","required":false,"in":"query","description":"Started on/after (ISO 8601).","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["video","image"]}},{"name":"sort","required":false,"in":"query","schema":{"type":"string","enum":["newest","oldest","impressions_desc"]}},{"name":"cursor","required":false,"in":"query","description":"Opaque pagination cursor.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":25,"default":25,"type":"number"}},{"name":"ids","required":false,"in":"query","description":"Batch-hydrate ad id tokens (comma-separated, max 25). When set, filters/pagination are ignored.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinAdSummary"}}}}}},"security":[{"oauth":[]}],"summary":"List (or batch-hydrate) LinkedIn ads from your tracked advertisers","tags":["Explore · LinkedIn Ads"]}},"/api/v1/explore/linkedin/ads/impressions":{"get":{"operationId":"batchLinkedinAdImpressions","parameters":[{"name":"from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"ids","required":false,"in":"query","description":"Ad id tokens (comma-separated, max 25).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinImpressionsTimeline"}}}}}},"security":[{"oauth":[]}],"summary":"Impression-bracket timeseries for multiple LinkedIn ads","tags":["Explore · LinkedIn Ads"]}},"/api/v1/explore/linkedin/ads/{id_token}":{"get":{"operationId":"getLinkedinAd","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"include","required":false,"in":"query","description":"Comma-separated heavy includes: full_targeting, transcript.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkedinAd"}}}}},"security":[{"oauth":[]}],"summary":"Get one LinkedIn ad","tags":["Explore · LinkedIn Ads"]}},"/api/v1/explore/linkedin/ads/{id_token}/impressions":{"get":{"operationId":"getLinkedinAdImpressions","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkedinImpressionsTimeline"}}}}},"security":[{"oauth":[]}],"summary":"Impression-bracket timeseries for one LinkedIn ad","tags":["Explore · LinkedIn Ads"]}},"/api/v1/explore/linkedin/ads/{id_token}/snapshots":{"get":{"operationId":"listLinkedinAdSnapshots","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Opaque pagination cursor.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":25,"default":25,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinAdSnapshot"}}}}}},"security":[{"oauth":[]}],"summary":"List point-in-time captures of one LinkedIn ad","tags":["Explore · LinkedIn Ads"]}},"/api/v1/explore/linkedin/ads/{id_token}/snapshots/{snapshot_uuid}":{"get":{"operationId":"getLinkedinAdAtSnapshot","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"snapshot_uuid","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkedinAd"}}}}},"security":[{"oauth":[]}],"summary":"Get a LinkedIn ad as captured at a snapshot","tags":["Explore · LinkedIn Ads"]}},"/api/v1/insights/meta/advertisers":{"get":{"operationId":"listMetaAdvertisers","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Advertiser"}}}}}},"security":[{"oauth":[]}],"summary":"List your tracked Meta advertisers","tags":["Insights · Meta"]},"post":{"operationId":"trackMetaAdvertiser","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaTrackBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedAdvertiser"}}}}},"security":[{"oauth":[]}],"summary":"Track a Meta advertiser","tags":["Insights · Meta"]}},"/api/v1/insights/meta/advertisers/{id_token}":{"get":{"operationId":"getMetaAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Advertiser"}}}}},"security":[{"oauth":[]}],"summary":"Get a tracked Meta advertiser","tags":["Insights · Meta"]},"delete":{"operationId":"untrackMetaAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"oauth":[]}],"summary":"Untrack a Meta advertiser","tags":["Insights · Meta"]}},"/api/v1/insights/meta/advertisers/{id_token}/summary":{"get":{"operationId":"getMetaAdvertiserSummary","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserInsight"}}}}},"security":[{"oauth":[]}],"summary":"AI insight summary for a tracked Meta advertiser","tags":["Insights · Meta"]}},"/api/v1/insights/meta/advertisers/{id_token}/reports/weekly":{"get":{"operationId":"getMetaAdvertiserWeeklyReport","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"week_start","required":false,"in":"query","description":"Week start date (ISO 8601). Omit for the latest report.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeeklyReport"}}}}},"security":[{"oauth":[]}],"summary":"Weekly report for a tracked Meta advertiser","tags":["Insights · Meta"]}},"/api/v1/insights/tiktok/advertisers":{"get":{"operationId":"listTiktokAdvertisers","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Advertiser"}}}}}},"security":[{"oauth":[]}],"summary":"List your tracked TikTok advertisers","tags":["Insights · TikTok"]},"post":{"operationId":"trackTiktokAdvertiser","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokTrackBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedAdvertiser"}}}}},"security":[{"oauth":[]}],"summary":"Track a TikTok advertiser","tags":["Insights · TikTok"]}},"/api/v1/insights/tiktok/advertisers/{id_token}":{"get":{"operationId":"getTiktokAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Advertiser"}}}}},"security":[{"oauth":[]}],"summary":"Get a tracked TikTok advertiser","tags":["Insights · TikTok"]},"delete":{"operationId":"untrackTiktokAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"oauth":[]}],"summary":"Untrack a TikTok advertiser","tags":["Insights · TikTok"]}},"/api/v1/insights/tiktok/advertisers/{id_token}/summary":{"get":{"operationId":"getTiktokAdvertiserSummary","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserInsight"}}}}},"security":[{"oauth":[]}],"summary":"AI insight summary for a tracked TikTok advertiser","tags":["Insights · TikTok"]}},"/api/v1/insights/tiktok/advertisers/{id_token}/reports/weekly":{"get":{"operationId":"getTiktokAdvertiserWeeklyReport","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"week_start","required":false,"in":"query","description":"Week start date (ISO 8601). Omit for the latest report.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeeklyReport"}}}}},"security":[{"oauth":[]}],"summary":"Weekly report for a tracked TikTok advertiser","tags":["Insights · TikTok"]}},"/api/v1/insights/google/advertisers":{"get":{"operationId":"listGoogleAdvertisers","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Advertiser"}}}}}},"security":[{"oauth":[]}],"summary":"List your tracked Google advertisers","tags":["Insights · Google"]},"post":{"operationId":"trackGoogleAdvertiser","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleTrackBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedAdvertiser"}}}}},"security":[{"oauth":[]}],"summary":"Track a Google advertiser","tags":["Insights · Google"]}},"/api/v1/insights/google/advertisers/{id_token}":{"get":{"operationId":"getGoogleAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Advertiser"}}}}},"security":[{"oauth":[]}],"summary":"Get a tracked Google advertiser","tags":["Insights · Google"]},"delete":{"operationId":"untrackGoogleAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"oauth":[]}],"summary":"Untrack a Google advertiser","tags":["Insights · Google"]}},"/api/v1/insights/google/advertisers/{id_token}/summary":{"get":{"operationId":"getGoogleAdvertiserSummary","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserInsight"}}}}},"security":[{"oauth":[]}],"summary":"AI insight summary for a tracked Google advertiser","tags":["Insights · Google"]}},"/api/v1/insights/google/advertisers/{id_token}/reports/weekly":{"get":{"operationId":"getGoogleAdvertiserWeeklyReport","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"week_start","required":false,"in":"query","description":"Week start date (ISO 8601). Omit for the latest report.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeeklyReport"}}}}},"security":[{"oauth":[]}],"summary":"Weekly report for a tracked Google advertiser","tags":["Insights · Google"]}},"/api/v1/insights/linkedin/advertisers":{"get":{"operationId":"listLinkedinAdvertisers","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Advertiser"}}}}}},"security":[{"oauth":[]}],"summary":"List your tracked LinkedIn advertisers","tags":["Insights · LinkedIn"]},"post":{"operationId":"trackLinkedinAdvertiser","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkedinTrackBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedAdvertiser"}}}}},"security":[{"oauth":[]}],"summary":"Track a LinkedIn advertiser","tags":["Insights · LinkedIn"]}},"/api/v1/insights/linkedin/advertisers/{id_token}":{"get":{"operationId":"getLinkedinAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Advertiser"}}}}},"security":[{"oauth":[]}],"summary":"Get a tracked LinkedIn advertiser","tags":["Insights · LinkedIn"]},"delete":{"operationId":"untrackLinkedinAdvertiser","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"oauth":[]}],"summary":"Untrack a LinkedIn advertiser","tags":["Insights · LinkedIn"]}},"/api/v1/insights/linkedin/advertisers/{id_token}/summary":{"get":{"operationId":"getLinkedinAdvertiserSummary","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserInsight"}}}}},"security":[{"oauth":[]}],"summary":"AI insight summary for a tracked LinkedIn advertiser","tags":["Insights · LinkedIn"]}},"/api/v1/insights/linkedin/advertisers/{id_token}/reports/weekly":{"get":{"operationId":"getLinkedinAdvertiserWeeklyReport","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"week_start","required":false,"in":"query","description":"Week start date (ISO 8601). Omit for the latest report.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeeklyReport"}}}}},"security":[{"oauth":[]}],"summary":"Weekly report for a tracked LinkedIn advertiser","tags":["Insights · LinkedIn"]}},"/api/v1/insights/tiktok-social/accounts":{"get":{"operationId":"listTiktokSocialAccounts","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SocialAccount"}}}}}},"security":[{"oauth":[]}],"summary":"List your tracked TikTok Organic accounts","tags":["Insights · TikTok Organic"]},"post":{"operationId":"trackTiktokSocialAccount","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccountTrackBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedSocialAccount"}}}}},"security":[{"oauth":[]}],"summary":"Track a TikTok Organic account","tags":["Insights · TikTok Organic"]}},"/api/v1/insights/tiktok-social/accounts/{id_token}":{"get":{"operationId":"getTiktokSocialAccount","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccount"}}}}},"security":[{"oauth":[]}],"summary":"Get a tracked TikTok Organic account","tags":["Insights · TikTok Organic"]},"delete":{"operationId":"untrackTiktokSocialAccount","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"oauth":[]}],"summary":"Untrack a TikTok Organic account","tags":["Insights · TikTok Organic"]}},"/api/v1/insights/tiktok-social/accounts/{id_token}/summary":{"get":{"operationId":"getTiktokSocialAccountSummary","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccountInsight"}}}}},"security":[{"oauth":[]}],"summary":"AI insight summary for a tracked TikTok Organic account","tags":["Insights · TikTok Organic"]}},"/api/v1/insights/tiktok-social/accounts/{id_token}/reports/weekly":{"get":{"operationId":"getTiktokSocialAccountWeeklyReport","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"week_start","required":false,"in":"query","description":"Week start date (ISO 8601). Omit for the latest report.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccountWeeklyReport"}}}}},"security":[{"oauth":[]}],"summary":"Weekly organic report for a tracked TikTok Organic account","tags":["Insights · TikTok Organic"]}},"/api/v1/insights/instagram-social/accounts":{"get":{"operationId":"listInstagramSocialAccounts","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SocialAccount"}}}}}},"security":[{"oauth":[]}],"summary":"List your tracked Instagram Organic accounts","tags":["Insights · Instagram Organic"]},"post":{"operationId":"trackInstagramSocialAccount","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccountTrackBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedSocialAccount"}}}}},"security":[{"oauth":[]}],"summary":"Track an Instagram Organic account","tags":["Insights · Instagram Organic"]}},"/api/v1/insights/instagram-social/accounts/{id_token}":{"get":{"operationId":"getInstagramSocialAccount","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccount"}}}}},"security":[{"oauth":[]}],"summary":"Get a tracked Instagram Organic account","tags":["Insights · Instagram Organic"]},"delete":{"operationId":"untrackInstagramSocialAccount","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"oauth":[]}],"summary":"Untrack an Instagram Organic account","tags":["Insights · Instagram Organic"]}},"/api/v1/insights/instagram-social/accounts/{id_token}/summary":{"get":{"operationId":"getInstagramSocialAccountSummary","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccountInsight"}}}}},"security":[{"oauth":[]}],"summary":"AI insight summary for a tracked Instagram Organic account","tags":["Insights · Instagram Organic"]}},"/api/v1/insights/instagram-social/accounts/{id_token}/reports/weekly":{"get":{"operationId":"getInstagramSocialAccountWeeklyReport","parameters":[{"name":"id_token","required":true,"in":"path","schema":{"type":"string"}},{"name":"week_start","required":false,"in":"query","description":"Week start date (ISO 8601). Omit for the latest report.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialAccountWeeklyReport"}}}}},"security":[{"oauth":[]}],"summary":"Weekly organic report for a tracked Instagram Organic account","tags":["Insights · Instagram Organic"]}},"/api/v1/analytics/meta/reach":{"get":{"operationId":"getMetaReach","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaReachChart"}}}}},"security":[{"oauth":[]}],"summary":"Meta reach over time, per advertiser","tags":["Analytics · Meta"]}},"/api/v1/analytics/meta/reach/regions":{"get":{"operationId":"getMetaReachRegions","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaReachRegionsChart"}}}}},"security":[{"oauth":[]}],"summary":"Meta reach by region","tags":["Analytics · Meta"]}},"/api/v1/analytics/meta/activity":{"get":{"operationId":"getMetaActivity","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaActivityChart"}}}}},"security":[{"oauth":[]}],"summary":"Meta new + active ad counts over time","tags":["Analytics · Meta"]}},"/api/v1/analytics/meta/regions":{"get":{"operationId":"getMetaRegions","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaRegionsChart"}}}}},"security":[{"oauth":[]}],"summary":"Meta available regions by reach","tags":["Analytics · Meta"]}},"/api/v1/analytics/meta/share-of-voice":{"get":{"operationId":"getMetaShareOfVoice","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaShareOfVoiceChart"}}}}},"security":[{"oauth":[]}],"summary":"Meta reach concentration (Lorenz / Gini) per advertiser","tags":["Analytics · Meta"]}},"/api/v1/analytics/meta/targeting":{"get":{"operationId":"getMetaTargeting","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaTargetingChart"}}}}},"security":[{"oauth":[]}],"summary":"Meta targeted vs excluded regions","tags":["Analytics · Meta"]}},"/api/v1/analytics/meta/top-ads":{"get":{"operationId":"getMetaTopAds","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaTopAdsChart"}}}}},"security":[{"oauth":[]}],"summary":"Meta top ads by reach","tags":["Analytics · Meta"]}},"/api/v1/analytics/tiktok/reach":{"get":{"operationId":"getTiktokReach","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokReachChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok reach over time, per advertiser","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/reach/regions":{"get":{"operationId":"getTiktokReachRegions","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokReachRegionsChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok reach by region, per advertiser","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/activity":{"get":{"operationId":"getTiktokActivity","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokActivityChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok new + active ad counts over time","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/regions":{"get":{"operationId":"getTiktokRegions","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokRegionsChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok available regions by ad count","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/share-of-voice":{"get":{"operationId":"getTiktokShareOfVoice","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokShareOfVoiceChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok share of voice across the set","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/runtime":{"get":{"operationId":"getTiktokRuntime","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokRuntimeChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok runtime distribution + optimal runtime","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/targeting":{"get":{"operationId":"getTiktokTargeting","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokTargetingChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok regional targeting overlap","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/creative":{"get":{"operationId":"getTiktokCreative","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokCreativeChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok creative mix (hook, format, audio)","tags":["Analytics · TikTok"]}},"/api/v1/analytics/tiktok/creative/{dimension}":{"get":{"operationId":"getTiktokCreativeDimension","parameters":[{"name":"dimension","required":true,"in":"path","schema":{"type":"string"}},{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TiktokCreativeDimensionChart"}}}}},"security":[{"oauth":[]}],"summary":"TikTok creative breakdown by one dimension","tags":["Analytics · TikTok"]}},"/api/v1/analytics/google/activity":{"get":{"operationId":"getGoogleActivity","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleActivityChart"}}}}},"security":[{"oauth":[]}],"summary":"Google new + active ad counts + impressions over time","tags":["Analytics · Google"]}},"/api/v1/analytics/google/regions":{"get":{"operationId":"getGoogleRegions","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleRegionsChart"}}}}},"security":[{"oauth":[]}],"summary":"Google available regions by ad count","tags":["Analytics · Google"]}},"/api/v1/analytics/google/share-of-voice":{"get":{"operationId":"getGoogleShareOfVoice","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleShareOfVoiceChart"}}}}},"security":[{"oauth":[]}],"summary":"Google reach concentration (Lorenz / Gini) per advertiser","tags":["Analytics · Google"]}},"/api/v1/analytics/google/runtime":{"get":{"operationId":"getGoogleRuntime","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleRuntimeChart"}}}}},"security":[{"oauth":[]}],"summary":"Google runtime distribution + optimal runtime","tags":["Analytics · Google"]}},"/api/v1/analytics/google/creative":{"get":{"operationId":"getGoogleCreative","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleCreativeChart"}}}}},"security":[{"oauth":[]}],"summary":"Google creative breakdown (default: content_format)","tags":["Analytics · Google"]}},"/api/v1/analytics/google/creative/{dimension}":{"get":{"operationId":"getGoogleCreativeDimension","parameters":[{"name":"dimension","required":true,"in":"path","schema":{"type":"string"}},{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleCreativeChart"}}}}},"security":[{"oauth":[]}],"summary":"Google creative breakdown by one dimension","tags":["Analytics · Google"]}},"/api/v1/analytics/google/stats":{"get":{"operationId":"getGoogleStats","parameters":[{"name":"advertiser_ids","required":false,"in":"query","description":"Comma-separated advertiser id tokens. Defaults to all tracked.","schema":{"example":"meta.advertiser.abc,meta.advertiser.def","type":"string"}},{"name":"date_from","required":false,"in":"query","description":"Start date (ISO 8601).","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"End date (ISO 8601).","schema":{"type":"string"}},{"name":"region_codes","required":false,"in":"query","description":"Comma-separated region codes (e.g. US,GB).","schema":{"type":"string"}},{"name":"granularity","required":false,"in":"query","schema":{"example":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleStatsChart"}}}}},"security":[{"oauth":[]}],"summary":"Google per-advertiser creative + impression stats","tags":["Analytics · Google"]}}},"info":{"title":"Adsmom API","description":"Stable REST API for tracked ad intelligence across Meta, TikTok, and Google. Authenticate with OAuth 2.0 client_credentials.","version":"1.0","contact":{}},"tags":[],"servers":[{"url":"/"}],"components":{"securitySchemes":{"oauth":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"UsageCredits":{"type":"object","properties":{"used":{"type":"number","description":"Credits consumed this period.","example":4210},"limit":{"type":"number","description":"Credit limit for this period.","example":5000},"remaining":{"type":"number","description":"Credits remaining this period.","example":790},"period_start":{"type":"string","nullable":true,"description":"Start of the current billing period (ISO 8601)."},"period_end":{"type":"string","nullable":true,"description":"End of the current billing period (ISO 8601)."}},"required":["used","limit","remaining","period_start","period_end"]},"UsageRateLimit":{"type":"object","properties":{"requests_per_minute":{"type":"number","description":"Requests allowed per window.","example":120}},"required":["requests_per_minute"]},"Usage":{"type":"object","properties":{"plan":{"type":"string","example":"BUSINESS"},"tracked_advertisers":{"type":"number","description":"Active tracked advertisers.","example":37},"credits":{"$ref":"#/components/schemas/UsageCredits"},"rate_limit":{"$ref":"#/components/schemas/UsageRateLimit"}},"required":["plan","tracked_advertisers","credits","rate_limit"]},"MetaAdvertiserRef":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/facebook/advertiser/0192f1c3-..."},"id_token":{"type":"string","example":"meta.advertiser.0192f1c3-..."},"name":{"type":"string","example":"Kaufland"}},"required":["gid","id_token","name"]},"MetaAdSummary":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/facebook/ad/0192f1c3-..."},"id_token":{"type":"string","example":"meta.ad.0192f1c3-..."},"platform":{"type":"string","enum":["meta"],"example":"meta"},"advertiser":{"$ref":"#/components/schemas/MetaAdvertiserRef"},"is_active":{"type":"boolean","example":true},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Delivery stop date; null while active."},"reach_total":{"type":"number","nullable":true,"description":"Lifetime breakdown reach from the Meta Ad Library."},"format":{"type":"string","enum":["video","image","unknown"]},"headline":{"type":"string","nullable":true,"description":"First creative link title."},"primary_text":{"type":"string","nullable":true,"description":"First creative body (truncated)."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."}},"required":["gid","id_token","platform","advertiser","is_active","start_date","end_date","reach_total","format","headline","primary_text","thumbnail_url"]},"MetaReachPoint":{"type":"object","properties":{"date":{"type":"string","example":"2026-05-12"},"reach":{"type":"number","example":84000}},"required":["date","reach"]},"MetaReachTimeline":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/facebook/ad/0192f1c3-..."},"id_token":{"type":"string","example":"meta.ad.0192f1c3-..."},"platform":{"type":"string","enum":["meta"],"example":"meta"},"daily":{"type":"array","items":{"$ref":"#/components/schemas/MetaReachPoint"}}},"required":["gid","id_token","platform","daily"]},"MetaAdMedia":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["video","image"]},"media_url":{"type":"string","nullable":true,"description":"Signed (~10 min). Video only."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed (~10 min)."}},"required":["id","type","media_url","thumbnail_url"]},"MetaTargeting":{"type":"object","properties":{"age_range":{"type":"string","nullable":true,"example":"25-54"},"gender":{"type":"string","nullable":true,"example":"All"},"locations":{"nullable":true,"description":"Targeted location names, when the source is a string list.","type":"array","items":{"type":"string"}}},"required":["age_range","gender","locations"]},"MetaAd":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/facebook/ad/0192f1c3-..."},"id_token":{"type":"string","example":"meta.ad.0192f1c3-..."},"platform":{"type":"string","enum":["meta"],"example":"meta"},"advertiser":{"$ref":"#/components/schemas/MetaAdvertiserRef"},"is_active":{"type":"boolean","example":true},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Delivery stop date; null while active."},"reach_total":{"type":"number","nullable":true,"description":"Lifetime breakdown reach from the Meta Ad Library."},"format":{"type":"string","enum":["video","image","unknown"]},"headline":{"type":"string","nullable":true,"description":"First creative link title."},"primary_text":{"type":"string","nullable":true,"description":"First creative body (truncated)."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."},"bodies":{"description":"All creative bodies.","type":"array","items":{"type":"string"}},"link_titles":{"description":"All creative link titles.","type":"array","items":{"type":"string"}},"link_captions":{"description":"All creative link captions.","type":"array","items":{"type":"string"}},"link_descriptions":{"description":"All creative link descriptions.","type":"array","items":{"type":"string"}},"languages":{"description":"Ad languages (ISO codes).","type":"array","items":{"type":"string"}},"media":{"type":"array","items":{"$ref":"#/components/schemas/MetaAdMedia"}},"targeting":{"nullable":true,"description":"Only with `include=full_targeting`; null otherwise.","allOf":[{"$ref":"#/components/schemas/MetaTargeting"}]}},"required":["gid","id_token","platform","advertiser","is_active","start_date","end_date","reach_total","format","headline","primary_text","thumbnail_url","bodies","link_titles","link_captions","link_descriptions","languages","media","targeting"]},"TiktokAdvertiserRef":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/advertiser/0192f1c3-..."},"id_token":{"type":"string","example":"tiktok.advertiser.0192f1c3-..."},"name":{"type":"string","example":"Kaufland"},"api_business_id":{"type":"string","nullable":true,"description":"TikTok-native business id."},"username":{"type":"string","nullable":true,"example":"@kaufland"}},"required":["gid","id_token","name","api_business_id","username"]},"TiktokAdSummary":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/ad/0192f1c3-..."},"id_token":{"type":"string","example":"tiktok.ad.0192f1c3-..."},"platform":{"type":"string","enum":["tiktok"],"example":"tiktok"},"api_id":{"type":"string","description":"TikTok-native ad id.","example":"17420..."},"advertiser":{"$ref":"#/components/schemas/TiktokAdvertiserRef"},"is_active":{"type":"boolean","example":true},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Last-shown date; null while active."},"reach_upper_bound":{"type":"number","nullable":true},"reach_lower_bound":{"type":"number","nullable":true},"format":{"type":"string","enum":["video","image","unknown"]},"primary_text":{"type":"string","nullable":true,"description":"Ad description."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."}},"required":["gid","id_token","platform","api_id","advertiser","is_active","start_date","end_date","reach_upper_bound","reach_lower_bound","format","primary_text","thumbnail_url"]},"TiktokReachPoint":{"type":"object","properties":{"date":{"type":"string","example":"2026-05-12"},"reach":{"type":"number","example":84000}},"required":["date","reach"]},"TiktokReachTimeline":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/ad/0192f1c3-..."},"id_token":{"type":"string","example":"tiktok.ad.0192f1c3-..."},"platform":{"type":"string","enum":["tiktok"],"example":"tiktok"},"daily":{"type":"array","items":{"$ref":"#/components/schemas/TiktokReachPoint"}}},"required":["gid","id_token","platform","daily"]},"TiktokAdMedia":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["video","image"]},"media_url":{"type":"string","nullable":true,"description":"Signed (~10 min)."},"cover_image_url":{"type":"string","nullable":true,"description":"Signed (~10 min)."},"description":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"hook_type":{"type":"string","nullable":true},"content_format":{"type":"string","nullable":true},"cta_type":{"type":"string","nullable":true},"audio_type":{"type":"string","nullable":true},"camera_perspective":{"type":"string","nullable":true},"psychological_trigger":{"type":"string","nullable":true},"visual_pacing":{"type":"string","nullable":true},"promotion_type":{"type":"string","nullable":true},"ad_category":{"type":"string","nullable":true},"sentiment":{"type":"string","nullable":true},"is_ugc":{"type":"boolean","nullable":true},"has_text_overlay":{"type":"boolean","nullable":true},"industries":{"nullable":true,"type":"array","items":{"type":"string"}},"brand_names":{"nullable":true,"type":"array","items":{"type":"string"}},"on_screen_text":{"type":"string","nullable":true,"description":"On-screen text. Only with `include=transcript`."},"spoken_content":{"type":"string","nullable":true,"description":"Spoken transcript. Only with `include=transcript`."}},"required":["id","type","media_url","cover_image_url","description","language","hook_type","content_format","cta_type","audio_type","camera_perspective","psychological_trigger","visual_pacing","promotion_type","ad_category","sentiment","is_ugc","has_text_overlay","industries","brand_names","on_screen_text","spoken_content"]},"TiktokRegionReach":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"reach":{"type":"number","example":120000}},"required":["region_code","reach"]},"TiktokTargeting":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"age_range":{"type":"string","example":"25-34"},"gender":{"type":"string","example":"female"}},"required":["region_code","age_range","gender"]},"TiktokAd":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/ad/0192f1c3-..."},"id_token":{"type":"string","example":"tiktok.ad.0192f1c3-..."},"platform":{"type":"string","enum":["tiktok"],"example":"tiktok"},"api_id":{"type":"string","description":"TikTok-native ad id.","example":"17420..."},"advertiser":{"$ref":"#/components/schemas/TiktokAdvertiserRef"},"is_active":{"type":"boolean","example":true},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Last-shown date; null while active."},"reach_upper_bound":{"type":"number","nullable":true},"reach_lower_bound":{"type":"number","nullable":true},"format":{"type":"string","enum":["video","image","unknown"]},"primary_text":{"type":"string","nullable":true,"description":"Ad description."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."},"media":{"type":"array","items":{"$ref":"#/components/schemas/TiktokAdMedia"}},"region_reach":{"description":"Per-region reach from the latest snapshot.","type":"array","items":{"$ref":"#/components/schemas/TiktokRegionReach"}},"targeting":{"nullable":true,"description":"Only with `include=full_targeting`; null otherwise.","type":"array","items":{"$ref":"#/components/schemas/TiktokTargeting"}}},"required":["gid","id_token","platform","api_id","advertiser","is_active","start_date","end_date","reach_upper_bound","reach_lower_bound","format","primary_text","thumbnail_url","media","region_reach","targeting"]},"TiktokAdSnapshot":{"type":"object","properties":{"uuid":{"type":"string","description":"Snapshot uuid — address one at /ads/{id}/snapshots/{uuid}."},"captured_at":{"type":"string","description":"When this capture was taken (ISO 8601)."},"is_active":{"type":"boolean","example":true},"last_shown_date":{"type":"string","nullable":true},"reach_upper_bound":{"type":"number","nullable":true},"reach_lower_bound":{"type":"number","nullable":true},"region_reach":{"type":"array","items":{"$ref":"#/components/schemas/TiktokRegionReach"}}},"required":["uuid","captured_at","is_active","last_shown_date","reach_upper_bound","reach_lower_bound","region_reach"]},"GoogleAdvertiserRef":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/google/advertiser/AR1234..."},"id_token":{"type":"string","example":"google.advertiser.AR1234..."},"name":{"type":"string","example":"Kaufland"},"origin_country":{"type":"string","nullable":true,"example":"DE"},"icon":{"type":"string","nullable":true}},"required":["gid","id_token","name","origin_country","icon"]},"GoogleAdSummary":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/google/ad/CR1234..."},"id_token":{"type":"string","example":"google.ad.CR1234..."},"platform":{"type":"string","enum":["google"],"example":"google"},"advertiser":{"$ref":"#/components/schemas/GoogleAdvertiserRef"},"is_active":{"type":"boolean","example":true,"description":"Shown within the last 30 days."},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Last-shown date; null while active."},"impression_lower_bound":{"type":"number","nullable":true},"impression_upper_bound":{"type":"number","nullable":true},"format":{"type":"string","enum":["video","image","text","unknown"]},"headline":{"type":"string","nullable":true},"primary_text":{"type":"string","nullable":true,"description":"Creative description (truncated)."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."}},"required":["gid","id_token","platform","advertiser","is_active","start_date","end_date","impression_lower_bound","impression_upper_bound","format","headline","primary_text","thumbnail_url"]},"GoogleAdMedia":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["video","image"]},"media_url":{"type":"string","nullable":true,"description":"Signed (~10 min)."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed (~10 min)."},"description":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"hook_type":{"type":"string","nullable":true},"content_format":{"type":"string","nullable":true},"cta_type":{"type":"string","nullable":true},"audio_type":{"type":"string","nullable":true},"camera_perspective":{"type":"string","nullable":true},"psychological_trigger":{"type":"string","nullable":true},"visual_pacing":{"type":"string","nullable":true},"promotion_type":{"type":"string","nullable":true},"ad_category":{"type":"string","nullable":true},"sentiment":{"type":"string","nullable":true},"is_ugc":{"type":"boolean","nullable":true},"has_text_overlay":{"type":"boolean","nullable":true},"industries":{"nullable":true,"type":"array","items":{"type":"string"}},"brand_names":{"nullable":true,"type":"array","items":{"type":"string"}},"on_screen_text":{"type":"string","nullable":true},"spoken_content":{"type":"string","nullable":true}},"required":["id","type","media_url","thumbnail_url","description","language","hook_type","content_format","cta_type","audio_type","camera_perspective","psychological_trigger","visual_pacing","promotion_type","ad_category","sentiment","is_ugc","has_text_overlay","industries","brand_names","on_screen_text","spoken_content"]},"GoogleTargeting":{"type":"object","properties":{"region_codes":{"description":"Region codes the ad was shown in (Google-internal codes).","type":"array","items":{"type":"string"}}},"required":["region_codes"]},"GoogleAd":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/google/ad/CR1234..."},"id_token":{"type":"string","example":"google.ad.CR1234..."},"platform":{"type":"string","enum":["google"],"example":"google"},"advertiser":{"$ref":"#/components/schemas/GoogleAdvertiserRef"},"is_active":{"type":"boolean","example":true,"description":"Shown within the last 30 days."},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Last-shown date; null while active."},"impression_lower_bound":{"type":"number","nullable":true},"impression_upper_bound":{"type":"number","nullable":true},"format":{"type":"string","enum":["video","image","text","unknown"]},"headline":{"type":"string","nullable":true},"primary_text":{"type":"string","nullable":true,"description":"Creative description (truncated)."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."},"call_to_action":{"type":"string","nullable":true},"destination_url":{"type":"string","nullable":true},"media":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAdMedia"}},"targeting":{"nullable":true,"description":"Only with `include=full_targeting`; null otherwise.","allOf":[{"$ref":"#/components/schemas/GoogleTargeting"}]}},"required":["gid","id_token","platform","advertiser","is_active","start_date","end_date","impression_lower_bound","impression_upper_bound","format","headline","primary_text","thumbnail_url","call_to_action","destination_url","media","targeting"]},"LinkedinAdvertiserRef":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/linkedin/advertiser/0192f1c3-..."},"id_token":{"type":"string","example":"linkedin.advertiser.0192f1c3-..."},"name":{"type":"string","example":"Microsoft"},"company_id":{"type":"string","nullable":true,"description":"LinkedIn /company/{id} key."}},"required":["gid","id_token","name","company_id"]},"LinkedinAdSummary":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/linkedin/ad/0192f1c3-..."},"id_token":{"type":"string","example":"linkedin.ad.0192f1c3-..."},"platform":{"type":"string","enum":["linkedin"],"example":"linkedin"},"api_id":{"type":"string","description":"LinkedIn Ad Library ad id.","example":"4623456789"},"advertiser":{"$ref":"#/components/schemas/LinkedinAdvertiserRef"},"is_active":{"type":"boolean","example":true,"description":"True for active or recently-active evidence. False covers both confirmed-inactive and unknown — read activity_status for the distinction."},"activity_status":{"type":"string","enum":["active","recently_active","inactive","unknown"],"example":"active","description":"Activity evidence at the latest observation. `recently_active` means the ad was seen in the library within the last crawl window; `unknown` means no evidence either way (never inferred as inactive)."},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Campaign end date; null while running."},"impressions_upper_bound":{"type":"number","nullable":true,"description":"EU impressions bracket upper bound (null for non-EU ads)."},"impressions_lower_bound":{"type":"number","nullable":true,"description":"EU impressions bracket lower bound (null for non-EU ads)."},"format":{"type":"string","enum":["video","image","unknown"]},"primary_text":{"type":"string","nullable":true,"description":"Headline, falling back to sponsored-post commentary."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."}},"required":["gid","id_token","platform","api_id","advertiser","is_active","activity_status","start_date","end_date","impressions_upper_bound","impressions_lower_bound","format","primary_text","thumbnail_url"]},"LinkedinImpressionsPoint":{"type":"object","properties":{"date":{"type":"string","example":"2026-05-12"},"impressions_lower_bound":{"type":"number","nullable":true,"example":10000},"impressions_upper_bound":{"type":"number","nullable":true,"example":50000}},"required":["date","impressions_lower_bound","impressions_upper_bound"]},"LinkedinImpressionsTimeline":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/linkedin/ad/0192f1c3-..."},"id_token":{"type":"string","example":"linkedin.ad.0192f1c3-..."},"platform":{"type":"string","enum":["linkedin"],"example":"linkedin"},"daily":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinImpressionsPoint"}}},"required":["gid","id_token","platform","daily"]},"LinkedinCountryImpression":{"type":"object","properties":{"country":{"type":"string","example":"Germany"},"percent":{"type":"number","nullable":true,"description":"Impression share, percent (LinkedIn reports shares, not counts).","example":34}},"required":["country","percent"]},"LinkedinAdMediaAnalysis":{"type":"object","properties":{"language":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"sentiment":{"type":"string","nullable":true},"hook_type":{"type":"string","nullable":true},"content_format":{"type":"string","nullable":true},"cta_type":{"type":"string","nullable":true},"has_text_overlay":{"type":"boolean","nullable":true},"topics":{"type":"array","items":{"type":"string"}},"on_screen_text":{"type":"string","nullable":true,"description":"On-screen text. Only with `include=transcript`."},"spoken_content":{"type":"string","nullable":true,"description":"Spoken transcript. Only with `include=transcript`."}},"required":["language","description","sentiment","hook_type","content_format","cta_type","has_text_overlay","topics","on_screen_text","spoken_content"]},"LinkedinAdMedia":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["video","image"]},"media_url":{"type":"string","nullable":true,"description":"Signed (~10 min)."},"cover_image_url":{"type":"string","nullable":true,"description":"Signed (~10 min)."},"analysis_status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Creative-analysis pipeline status."},"analysis":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/LinkedinAdMediaAnalysis"}]}},"required":["id","type","media_url","cover_image_url","analysis_status","analysis"]},"LinkedinTargetingSegment":{"type":"object","properties":{"category":{"type":"string","example":"Location"},"visible":{"type":"string","nullable":true},"hidden":{"type":"string","nullable":true}},"required":["category","visible","hidden"]},"LinkedinTargetingParameter":{"type":"object","properties":{"parameter":{"type":"string","example":"Member skills"},"targeted":{"type":"boolean"},"excluded":{"type":"boolean"}},"required":["parameter","targeted","excluded"]},"LinkedinTargeting":{"type":"object","properties":{"segments":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinTargetingSegment"}},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinTargetingParameter"}}},"required":["segments","parameters"]},"LinkedinAd":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/linkedin/ad/0192f1c3-..."},"id_token":{"type":"string","example":"linkedin.ad.0192f1c3-..."},"platform":{"type":"string","enum":["linkedin"],"example":"linkedin"},"api_id":{"type":"string","description":"LinkedIn Ad Library ad id.","example":"4623456789"},"advertiser":{"$ref":"#/components/schemas/LinkedinAdvertiserRef"},"is_active":{"type":"boolean","example":true,"description":"True for active or recently-active evidence. False covers both confirmed-inactive and unknown — read activity_status for the distinction."},"activity_status":{"type":"string","enum":["active","recently_active","inactive","unknown"],"example":"active","description":"Activity evidence at the latest observation. `recently_active` means the ad was seen in the library within the last crawl window; `unknown` means no evidence either way (never inferred as inactive)."},"start_date":{"type":"string","nullable":true,"example":"2026-05-01"},"end_date":{"type":"string","nullable":true,"description":"Campaign end date; null while running."},"impressions_upper_bound":{"type":"number","nullable":true,"description":"EU impressions bracket upper bound (null for non-EU ads)."},"impressions_lower_bound":{"type":"number","nullable":true,"description":"EU impressions bracket lower bound (null for non-EU ads)."},"format":{"type":"string","enum":["video","image","unknown"]},"primary_text":{"type":"string","nullable":true,"description":"Headline, falling back to sponsored-post commentary."},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed, short-lived (~10 min). Fetch promptly or re-request."},"headline":{"type":"string","nullable":true},"commentary":{"type":"string","nullable":true},"cta_text":{"type":"string","nullable":true},"destination_url":{"type":"string","nullable":true},"creative_type":{"type":"string","nullable":true},"ad_format":{"type":"string","nullable":true},"payer_name":{"type":"string","nullable":true,"description":"\"Paid for by\" entity from the ad detail page."},"country_impressions":{"description":"Per-country impression shares from the latest snapshot.","type":"array","items":{"$ref":"#/components/schemas/LinkedinCountryImpression"}},"media":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinAdMedia"}},"targeting":{"nullable":true,"description":"Only with `include=full_targeting`; null otherwise.","allOf":[{"$ref":"#/components/schemas/LinkedinTargeting"}]}},"required":["gid","id_token","platform","api_id","advertiser","is_active","activity_status","start_date","end_date","impressions_upper_bound","impressions_lower_bound","format","primary_text","thumbnail_url","headline","commentary","cta_text","destination_url","creative_type","ad_format","payer_name","country_impressions","media","targeting"]},"LinkedinAdSnapshot":{"type":"object","properties":{"uuid":{"type":"string","description":"Snapshot uuid — address one at /ads/{id}/snapshots/{uuid}."},"captured_at":{"type":"string","description":"When this capture was taken (ISO 8601)."},"is_active":{"type":"boolean","nullable":true},"total_impressions":{"type":"string","nullable":true,"description":"Raw impressions bracket as displayed (e.g. \"10k-50k\")."},"impressions_lower_bound":{"type":"number","nullable":true},"impressions_upper_bound":{"type":"number","nullable":true},"country_impressions":{"type":"array","items":{"$ref":"#/components/schemas/LinkedinCountryImpression"}}},"required":["uuid","captured_at","is_active","total_impressions","impressions_lower_bound","impressions_upper_bound","country_impressions"]},"Advertiser":{"type":"object","properties":{"gid":{"type":"string","description":"Canonical global id. Use the slash-free form in path params.","example":"gid://adsmom/tiktok/advertiser/123456"},"id_token":{"type":"string","description":"Slash-free id token for use in URL path segments.","example":"tiktok.advertiser.123456"},"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"example":"tiktok"},"name":{"type":"string","description":"Advertiser / page display name.","example":"Kaufland"}},"required":["gid","id_token","platform","name"]},"MetaTrackBody":{"type":"object","properties":{"query":{"type":"string","description":"Facebook page name, handle, or numeric page id. A numeric id is matched exactly; otherwise the top page-search result is tracked."}},"required":["query"]},"TrackedAdvertiser":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/advertiser/7100"},"id_token":{"type":"string","example":"tiktok.advertiser.7100"},"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"name":{"type":"string","example":"Kaufland"},"external_id":{"type":"string","nullable":true,"description":"Platform-native business id, when resolved."},"is_active":{"type":"boolean","example":true},"pending_ingest":{"type":"boolean","description":"True when the ingest crawl has not completed yet."},"tracked_at":{"type":"string","nullable":true}},"required":["gid","id_token","platform","name","external_id","is_active","pending_ingest","tracked_at"]},"AdvertiserInsight":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/advertiser/7100"},"id_token":{"type":"string","example":"tiktok.advertiser.7100"},"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"status":{"type":"string","description":"Generation status (e.g. completed, pending)."},"generated_at":{"type":"string","nullable":true},"total_ads_analyzed":{"type":"number","nullable":true},"page_summary":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"ad_analysis":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"initial_assessment":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"recommendations":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."}},"required":["gid","id_token","platform","status","generated_at","total_ads_analyzed","page_summary","ad_analysis","initial_assessment","recommendations"]},"WeeklyReport":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/advertiser/7100"},"id_token":{"type":"string","example":"tiktok.advertiser.7100"},"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"]},"week_start":{"type":"string","example":"2026-06-15"},"week_end":{"type":"string","example":"2026-06-21"},"created_at":{"type":"string","nullable":true},"report":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"metrics":{"type":"object","nullable":true},"previous_metrics":{"type":"object","nullable":true}},"required":["gid","id_token","platform","week_start","week_end","created_at","report","metrics","previous_metrics"]},"TiktokTrackBody":{"type":"object","properties":{"ad_id":{"type":"string","description":"A TikTok ad api_id; the parent advertiser is resolved from it server-side."}},"required":["ad_id"]},"GoogleTrackBody":{"type":"object","properties":{"advertiser_id":{"type":"string","description":"A Google Ad Library advertiser id."}},"required":["advertiser_id"]},"LinkedinTrackBody":{"type":"object","properties":{"company_id":{"type":"string","description":"Exact LinkedIn /company/{id} key (numeric id or vanity slug)."},"company_url":{"type":"string","description":"LinkedIn company URL, e.g. https://www.linkedin.com/company/microsoft/. The /company/ segment is used as the exact key."},"name":{"type":"string","description":"Advertiser display name. Must uniquely match an already-discovered advertiser; otherwise a discovery crawl is started and the request should be retried."}}},"SocialAccount":{"type":"object","properties":{"gid":{"type":"string","description":"Canonical global id. Use the slash-free form in path params.","example":"gid://adsmom/tiktok-social/account/123456"},"id_token":{"type":"string","description":"Slash-free id token for use in URL path segments.","example":"tiktok-social.account.123456"},"platform":{"type":"string","enum":["tiktok-social","instagram-social"],"example":"tiktok-social"},"handle":{"type":"string","description":"Account handle / username.","example":"nike"},"name":{"type":"string","description":"Account display name.","example":"Nike"},"follower_count":{"type":"number","nullable":true,"description":"Latest crawled follower count, when known."}},"required":["gid","id_token","platform","handle","name","follower_count"]},"SocialAccountTrackBody":{"type":"object","properties":{"handle":{"type":"string","description":"Account handle to track — an @handle, a bare handle, or a profile URL (tiktok.com/@x, instagram.com/x). Tracking kicks off a crawl; posts appear a few minutes later.","example":"@nike"}},"required":["handle"]},"TrackedSocialAccount":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok-social/account/7100"},"id_token":{"type":"string","example":"tiktok-social.account.7100"},"platform":{"type":"string","enum":["tiktok-social","instagram-social"]},"handle":{"type":"string","example":"nike"},"name":{"type":"string","example":"Nike"},"follower_count":{"type":"number","nullable":true},"is_active":{"type":"boolean","example":true},"pending_ingest":{"type":"boolean","description":"True when the ingest crawl has not completed yet."},"tracked_at":{"type":"string","nullable":true}},"required":["gid","id_token","platform","handle","name","follower_count","is_active","pending_ingest","tracked_at"]},"SocialAccountInsight":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok-social/account/7100"},"id_token":{"type":"string","example":"tiktok-social.account.7100"},"platform":{"type":"string","enum":["tiktok-social","instagram-social"]},"status":{"type":"string","description":"Generation status (e.g. completed, pending)."},"generated_at":{"type":"string","nullable":true},"total_posts_analyzed":{"type":"number","nullable":true},"page_summary":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"content_analysis":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"initial_assessment":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"recommendations":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."}},"required":["gid","id_token","platform","status","generated_at","total_posts_analyzed","page_summary","content_analysis","initial_assessment","recommendations"]},"SocialAccountWeeklyReport":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok-social/account/7100"},"id_token":{"type":"string","example":"tiktok-social.account.7100"},"platform":{"type":"string","enum":["tiktok-social","instagram-social"]},"week_start":{"type":"string","example":"2026-06-15"},"week_end":{"type":"string","example":"2026-06-21"},"created_at":{"type":"string","nullable":true},"report":{"type":"object","nullable":true,"description":"AI-generated; structure may evolve."},"metrics":{"type":"object","nullable":true},"previous_metrics":{"type":"object","nullable":true}},"required":["gid","id_token","platform","week_start","week_end","created_at","report","metrics","previous_metrics"]},"AnalyticsAdvertiserRef":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/tiktok/advertiser/123456"},"id_token":{"type":"string","example":"tiktok.advertiser.123456"},"platform":{"type":"string","enum":["meta","tiktok","google"],"example":"tiktok"},"name":{"type":"string","example":"Kaufland"}},"required":["gid","id_token","platform","name"]},"MetaReachSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"points":{"type":"array","items":{"$ref":"#/components/schemas/MetaReachPoint"}}},"required":["advertiser","points"]},"MetaReachChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/MetaReachSeries"}}},"required":["series"]},"MetaRegionReachPart":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"reach":{"type":"number","example":92100}},"required":["advertiser","reach"]},"MetaRegionReach":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"total_reach":{"type":"number","example":184200},"per_advertiser":{"type":"array","items":{"$ref":"#/components/schemas/MetaRegionReachPart"}}},"required":["region_code","total_reach","per_advertiser"]},"MetaReachRegionsChart":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/MetaRegionReach"}}},"required":["regions"]},"MetaActivityPoint":{"type":"object","properties":{"bucket_start":{"type":"string","example":"2026-05-08"},"bucket_end":{"type":"string","example":"2026-05-09"},"new_ads":{"type":"number","example":12},"active_ads":{"type":"number","example":47}},"required":["bucket_start","bucket_end","new_ads","active_ads"]},"MetaActivitySeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"points":{"type":"array","items":{"$ref":"#/components/schemas/MetaActivityPoint"}}},"required":["advertiser","points"]},"MetaActivityChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/MetaActivitySeries"}}},"required":["series"]},"MetaRegion":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"total_reach":{"type":"number","example":184200}},"required":["region_code","total_reach"]},"MetaRegionsChart":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/MetaRegion"}}},"required":["regions"]},"ConcentrationPoint":{"type":"object","properties":{"pct_ads":{"type":"number","description":"Cumulative share of ads (0..1).","example":0.2},"pct_reach":{"type":"number","description":"Cumulative share of reach (0..1).","example":0.65}},"required":["pct_ads","pct_reach"]},"MetaShareOfVoiceSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"ad_count":{"type":"number","example":124},"total_reach":{"type":"number","example":4820000},"gini":{"type":"number","description":"Gini coefficient (0..1).","example":0.62},"lorenz":{"type":"array","items":{"$ref":"#/components/schemas/ConcentrationPoint"}},"top_reaches":{"type":"array","items":{"type":"number"}}},"required":["advertiser","ad_count","total_reach","gini","lorenz","top_reaches"]},"MetaShareOfVoiceChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/MetaShareOfVoiceSeries"}}},"required":["series"]},"MetaTargetingPart":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"ad_count":{"type":"number","example":18},"excluded_count":{"type":"number","example":2}},"required":["advertiser","ad_count","excluded_count"]},"MetaTargetedRegion":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"ad_count":{"type":"number","example":31},"excluded_count":{"type":"number","example":4},"per_advertiser":{"type":"array","items":{"$ref":"#/components/schemas/MetaTargetingPart"}}},"required":["region_code","ad_count","excluded_count","per_advertiser"]},"MetaTargetingChart":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/MetaTargetedRegion"}}},"required":["regions"]},"MetaTopAdRow":{"type":"object","properties":{"gid":{"type":"string","example":"gid://adsmom/facebook/ad/0f9c…"},"id_token":{"type":"string","example":"meta.ad.0f9c…"},"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"headline":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"started_at":{"type":"string","nullable":true,"example":"2026-04-01"},"ended_at":{"type":"string","nullable":true,"example":"2026-05-20"},"total_reach":{"type":"number","example":318400}},"required":["gid","id_token","advertiser","headline","body","thumbnail_url","started_at","ended_at","total_reach"]},"MetaTopAdsChart":{"type":"object","properties":{"ads":{"type":"array","items":{"$ref":"#/components/schemas/MetaTopAdRow"}}},"required":["ads"]},"TiktokReachSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"points":{"type":"array","items":{"$ref":"#/components/schemas/TiktokReachPoint"}}},"required":["advertiser","points"]},"TiktokReachChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/TiktokReachSeries"}}},"required":["series"]},"TiktokRegionImpressions":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"impressions":{"type":"number","example":920000}},"required":["region_code","impressions"]},"TiktokReachRegionSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"regions":{"type":"array","items":{"$ref":"#/components/schemas/TiktokRegionImpressions"}}},"required":["advertiser","regions"]},"TiktokReachRegionsChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/TiktokReachRegionSeries"}}},"required":["series"]},"TiktokActivityPoint":{"type":"object","properties":{"period_start":{"type":"string","example":"2026-05-01"},"period_end":{"type":"string","example":"2026-05-08"},"new_ads":{"type":"number","example":12},"active_ads":{"type":"number","example":47}},"required":["period_start","period_end","new_ads","active_ads"]},"TiktokActivitySeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"points":{"type":"array","items":{"$ref":"#/components/schemas/TiktokActivityPoint"}}},"required":["advertiser","points"]},"TiktokActivityChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/TiktokActivitySeries"}}},"required":["series"]},"TiktokRegion":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"ad_count":{"type":"number","example":84}},"required":["region_code","ad_count"]},"TiktokRegionsChart":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/TiktokRegion"}}},"required":["regions"]},"TiktokShareOfVoiceEntry":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"total_reach":{"type":"number","example":4820000},"total_ads":{"type":"number","example":124},"percentage":{"type":"number","description":"Share of the set total (0..100).","example":38.4}},"required":["advertiser","total_reach","total_ads","percentage"]},"TiktokShareOfVoiceChart":{"type":"object","properties":{"advertisers":{"type":"array","items":{"$ref":"#/components/schemas/TiktokShareOfVoiceEntry"}}},"required":["advertisers"]},"RuntimeBucket":{"type":"object","properties":{"label":{"type":"string","example":"8-14d"},"count":{"type":"number","example":23}},"required":["label","count"]},"TiktokRuntimeSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeBucket"}}},"required":["advertiser","buckets"]},"TiktokOptimalRuntimeEntry":{"type":"object","properties":{"label":{"type":"string","example":"8-14d"},"avg_reach":{"type":"number","example":142000},"ad_count":{"type":"number","example":23}},"required":["label","avg_reach","ad_count"]},"TiktokRuntimeChart":{"type":"object","properties":{"distribution":{"type":"array","items":{"$ref":"#/components/schemas/TiktokRuntimeSeries"}},"optimal":{"type":"array","items":{"$ref":"#/components/schemas/TiktokOptimalRuntimeEntry"}}},"required":["distribution","optimal"]},"TiktokTargetingRegion":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"advertisers":{"description":"Display names of tracked advertisers targeting this region.","example":["Kaufland","Lidl"],"type":"array","items":{"type":"string"}}},"required":["region_code","advertisers"]},"TiktokTargetingChart":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/TiktokTargetingRegion"}}},"required":["regions"]},"CreativeMixEntry":{"type":"object","properties":{"value":{"type":"string","example":"problem_solution"},"count":{"type":"number","example":42}},"required":["value","count"]},"TiktokCreativeSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"hook_types":{"type":"array","items":{"$ref":"#/components/schemas/CreativeMixEntry"}},"content_formats":{"type":"array","items":{"$ref":"#/components/schemas/CreativeMixEntry"}},"audio_types":{"type":"array","items":{"$ref":"#/components/schemas/CreativeMixEntry"}}},"required":["advertiser","hook_types","content_formats","audio_types"]},"TiktokCreativeChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/TiktokCreativeSeries"}}},"required":["series"]},"TiktokCreativeDimensionSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/CreativeMixEntry"}}},"required":["advertiser","breakdown"]},"TiktokCreativeDimensionChart":{"type":"object","properties":{"dimension":{"type":"string","enum":["hook_type","content_format","audio_type"]},"series":{"type":"array","items":{"$ref":"#/components/schemas/TiktokCreativeDimensionSeries"}}},"required":["dimension","series"]},"GoogleActivityPoint":{"type":"object","properties":{"period_start":{"type":"string","example":"2026-05-01"},"new_ads":{"type":"number","example":12},"active_ads":{"type":"number","example":47},"impressions":{"type":"number","description":"Prorated impressions for the bucket (upper bound).","example":142000}},"required":["period_start","new_ads","active_ads","impressions"]},"GoogleActivitySeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"points":{"type":"array","items":{"$ref":"#/components/schemas/GoogleActivityPoint"}}},"required":["advertiser","points"]},"GoogleActivityChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/GoogleActivitySeries"}}},"required":["series"]},"GoogleRegion":{"type":"object","properties":{"region_code":{"type":"string","example":"US"},"ad_count":{"type":"number","example":84}},"required":["region_code","ad_count"]},"GoogleRegionsChart":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/GoogleRegion"}}},"required":["regions"]},"GoogleShareOfVoiceSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"ad_count":{"type":"number","example":124},"awaiting_count":{"type":"number","description":"Ads still awaiting an impression estimate.","example":6},"total_reach":{"type":"number","example":4820000},"gini":{"type":"number","description":"Gini coefficient (0..1).","example":0.62},"lorenz":{"type":"array","items":{"$ref":"#/components/schemas/ConcentrationPoint"}}},"required":["advertiser","ad_count","awaiting_count","total_reach","gini","lorenz"]},"GoogleShareOfVoiceChart":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/GoogleShareOfVoiceSeries"}}},"required":["series"]},"GoogleRuntimeSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeBucket"}}},"required":["advertiser","buckets"]},"GoogleOptimalRuntimeBucket":{"type":"object","properties":{"label":{"type":"string","example":"8-14d"},"count":{"type":"number","example":23},"avg_impressions":{"type":"number","example":142000}},"required":["label","count","avg_impressions"]},"GoogleOptimalRuntimeSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/GoogleOptimalRuntimeBucket"}}},"required":["advertiser","buckets"]},"GoogleRuntimeChart":{"type":"object","properties":{"distribution":{"type":"array","items":{"$ref":"#/components/schemas/GoogleRuntimeSeries"}},"optimal":{"type":"array","items":{"$ref":"#/components/schemas/GoogleOptimalRuntimeSeries"}}},"required":["distribution","optimal"]},"GoogleCreativeBucket":{"type":"object","properties":{"value":{"type":"string","example":"video"},"count":{"type":"number","example":42},"impressions":{"type":"number","example":142000}},"required":["value","count","impressions"]},"GoogleCreativeSeries":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/GoogleCreativeBucket"}}},"required":["advertiser","breakdown"]},"GoogleCreativeChart":{"type":"object","properties":{"dimension":{"type":"string","example":"content_format"},"series":{"type":"array","items":{"$ref":"#/components/schemas/GoogleCreativeSeries"}}},"required":["dimension","series"]},"GoogleImpressionRange":{"type":"object","properties":{"lower_bound":{"type":"number","example":100000},"upper_bound":{"type":"number","example":1000000}},"required":["lower_bound","upper_bound"]},"GoogleRegionImpression":{"type":"object","properties":{"region_code":{"type":"string","nullable":true,"example":"US"},"lower_bound":{"type":"number","example":100000},"upper_bound":{"type":"number","example":1000000}},"required":["region_code","lower_bound","upper_bound"]},"GoogleSurfaceImpression":{"type":"object","properties":{"surface":{"type":"string","example":"YOUTUBE"},"lower_bound":{"type":"number","example":100000},"upper_bound":{"type":"number","example":1000000}},"required":["surface","lower_bound","upper_bound"]},"GoogleStatsEntry":{"type":"object","properties":{"advertiser":{"$ref":"#/components/schemas/AnalyticsAdvertiserRef"},"origin_country":{"type":"string","example":"US"},"image_count":{"type":"number","nullable":true},"text_count":{"type":"number","nullable":true},"video_count":{"type":"number","nullable":true},"active_count":{"type":"number","nullable":true},"ended_count":{"type":"number","nullable":true},"total_impressions":{"$ref":"#/components/schemas/GoogleImpressionRange"},"regions":{"type":"array","items":{"$ref":"#/components/schemas/GoogleRegionImpression"}},"surfaces":{"type":"array","items":{"$ref":"#/components/schemas/GoogleSurfaceImpression"}}},"required":["advertiser","origin_country","image_count","text_count","video_count","active_count","ended_count","total_impressions","regions","surfaces"]},"GoogleStatsChart":{"type":"object","properties":{"advertisers":{"type":"array","items":{"$ref":"#/components/schemas/GoogleStatsEntry"}}},"required":["advertisers"]}}}}