Docs · methods

Ads

Ads collected from the Google Transparency Center and the Meta Ad Library. A competitor produces Google ads once its googleAdvertiserId is set, Meta ads once its facebookPageId is set; list_competitors shows both.

get_google_ads · get_meta_ads

01

Get Google ads

get_google_adsread

Google Transparency Center ads for a project's competitors. sourceGranted false means the organization does not have Google ads tracking enabled, which is different from having no ads.

Parameters8

  • projectIdintegerRequiredProject id from list_projects. Every scoped method needs it.
  • competitorIdintegerOptionalCompetitor id from list_competitors. Omit to cover every tracked competitor in the project.
  • fromISO dateOptionalOnly items published on or after this date, e.g. 2026-08-01.
  • toISO dateOptionalOnly items published on or before this date.
  • formatstringOptionalCreative format filter, e.g. "text", "image", "video".
  • searchstringOptionalFree-text match against the ad title and body.
  • pageintegerOptional1-based page number. Defaults to 1.
  • sizeintegerOptionalAds per page. Defaults to 12, clamped to 48.

Returns5

  • items[]adtitle, body, ctaText, linkUrl, previewUrl, format, isActive, startedAt, endedAt, mediaUrls, competitorName.
  • emptyReasonstring | nullSet when empty: missing advertiser id, no competitors, or nothing stored in range.
  • totalintegerUnfiltered count.
  • pageinteger
  • sourceGrantedbooleanFalse means this ad source is not enabled for the organization, which is different from having no ads.
02

Get Meta ads

get_meta_adsread

Meta Ad Library ads for a project's competitors, with an optional surface filter (Facebook, Instagram, Messenger, Threads, Audience Network).

Parameters9

  • projectIdintegerRequiredProject id from list_projects. Every scoped method needs it.
  • competitorIdintegerOptionalCompetitor id from list_competitors. Omit to cover every tracked competitor in the project.
  • fromISO dateOptionalOnly items published on or after this date, e.g. 2026-08-01.
  • toISO dateOptionalOnly items published on or before this date.
  • formatstringOptionalCreative format filter, e.g. "image", "video", "carousel".
  • searchstringOptionalFree-text match against the ad title and body.
  • pageintegerOptional1-based page number. Defaults to 1.
  • sizeintegerOptionalAds per page. Defaults to 12, clamped to 48.
  • publisherPlatformenumOptionalFACEBOOK, INSTAGRAM, MESSENGER, THREADS or AUDIENCE_NETWORK.

Returns6

  • items[]adtitle, body, ctaText, linkUrl, previewUrl, format, isActive, startedAt, endedAt, mediaUrls, competitorName.
  • emptyReasonstring | nullSet when empty: missing advertiser id, no competitors, or nothing stored in range.
  • totalintegerUnfiltered count.
  • pageinteger
  • sourceGrantedbooleanFalse means this ad source is not enabled for the organization, which is different from having no ads.
  • items[].publisherPlatformsstring[]The Meta surfaces each ad ran on.
← Social posts