search_ads

Searches the Meta ads of Shopify stores with the same filters and ranking as the Ads page of the dashboard. Each result includes the ad copy, a thumbnail, its run dates, and the store behind it. Cost: 1 credit per successful call.

Arguments

Store filters apply to the store that runs the ad. Here, query matches ad copy, Facebook page names, and store names.

Argument	Type	Allowed values
`query`	string	Free text, matched like the search box of the dashboard page (for example product titles, store names, and domains). 1 to 200 characters.
`niches`	array of strings or integers	Niche names or ids from `list_filter_options` with `kind: "niches"`. A parent niche includes its sub-niches. Up to 20.
`countries`	array of strings	Store countries as ISO 3166-1 alpha-2 codes, for example `US`, `FR`. Up to 50.
`currencies`	array of strings	Store currencies as ISO 4217 codes, for example `USD`, `EUR`.
`languages`	array of enums	Storefront languages: `English`, `French`, `Spanish`, `German`, `Italian`, `Portuguese`, `Dutch`, `Polish`, `Norwegian`, `Swedish`, `Danish`, `Finnish`, `Chinese`, `Japanese`, `Korean`, `Arabic`, `Russian`, `Turkish`, `Hindi`, `Thai`, `Vietnamese`, `Indonesian`, `Greek`, `Czech`, `Hungarian`, `Romanian`.
`domains`	array of strings	Domain extensions, for example `.com`, `.fr`, `.co.uk`.
`pixels`	array of enums	Tracking pixels on the store: `TikTok`, `Snapchat`, `Facebook`, `Instagram`, `Google`, `Twitter`, `Pinterest`, `Reddit`, `TripleWhale`, `Applovin`.
`themes`	array of strings	Shopify theme names from `list_filter_options` with `kind: "themes"`.
`apps`	array of strings	Installed Shopify app names from `list_filter_options` with `kind: "apps"` and a `query`.
`social_networks`	array of enums	Social networks linked from the store: `Facebook`, `Instagram`, `TikTok`, `YouTube`, `Pinterest`, `Twitter`, `Snapchat`, `Reddit`.
`monthly_revenue`	range	Estimated monthly revenue, in the store’s currency.
`monthly_visits`	range	Estimated monthly visits.
`traffic_growth_pct`	range	Traffic growth score, in percent: the store’s month-over-month changes in visits, added up over the months Copyfy has on record. Accepts negative values.
`active_ads`	range	Number of currently active Meta ads.
`products_count`	range	Catalog size (number of products).
`monthly_orders`	range	Estimated monthly orders.
`shop_created_between`	date range	Store creation date: `{ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }`. Either bound can be omitted.
`page`	integer	1 to 20. Default: `1`.
`per_page`	integer	1 to 25. Default: `10`.

A range is an object { "min": number, "max": number }. Both bounds are optional and must be zero or more, except for traffic_growth_pct. Every argument is optional: with no filters, you get the same default ranking as the dashboard. Ad-specific arguments:

Argument	Type	Allowed values
`avg_price`	range	Average product price of the store, in the store’s currency.
`media_types`	array of enums	`video`, `image`, `carousel`, `dco` (dynamic creative), `dpa` (dynamic product ads).
`status`	enum	`all`, `active`, `inactive`. Default: `all`.
`ctas`	array of enums	`Shop Now`, `Learn More`, `Buy Now`, `Order Now`, `Get Offer`, `Call Now`, `View product`, `Sign Up`, `Download`, `Watch More`, `Contact Us`, `Book Now`, `Get Quote`, `Subscribe`.
`active_days`	range	Days the ad has been running. Only matches ads still running: combining it with `status: "inactive"` returns `invalid_arguments`.
`ad_started_between`	date range	Ad start date: `{ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }`. Either bound can be omitted.
`partnership_only`	boolean	`true` keeps only partnership (branded content) ads.
`trustpilot_rating`	range	Trustpilot rating of the store, 0 to 5.
`trustpilot_reviews`	range	Number of Trustpilot reviews of the store.
`sort_by`	enum	`recommended`, `newest`, `oldest`, `reach`, `revenue`, `traffic`, `traffic_growth`. Default: `recommended`.
`sort_order`	enum	`asc`, `desc`. Default: `desc`. Applies to `revenue`, `reach`, `traffic`, and `traffic_growth`.

recommended is the dashboard default: one ad per store, stores with the most active ads first. reach and traffic rank by the store’s traffic, and revenue by the store’s revenue.

Example

Active video ads that started since August 24, 2026, from stores in the Beauty niche:

Tool call

{
  "name": "search_ads",
  "arguments": {
    "niches": ["Beauty"],
    "media_types": ["video"],
    "status": "active",
    "ad_started_between": { "from": "2026-08-24" },
    "sort_by": "reach",
    "per_page": 5
  }
}

Result (trimmed)

{
  "results": [
    {
      "id": 5521907,
      "ad_archive_id": "1187340029915522",
      "page_name": "Example Glow",
      "status": "active",
      "media_type": "video",
      "headline": "Back in stock",
      "ad_text": "Our best-selling serum is back in stock. Visible results in 14 days or your money back.",
      "cta": "Shop Now",
      "landing_url": "https://example-glow.com/products/vitamin-c-serum",
      "image_url": "https://bucket.copyfy.io/ads/example-glow-preview.jpg",
      "ad_library_url": "https://www.facebook.com/ads/library/?id=1187340029915522",
      "started_at": "2026-08-29",
      "last_seen_at": "2026-09-23",
      "active_days": 26,
      "is_partnership": false,
      "shop": {
        "id": 845120,
        "name": "Example Glow",
        "domain": "example-glow.com",
        "country": "US",
        "active_ads": 58
      },
      "dashboard_url": "https://app.copyfy.io/dashboard/track/845120"
    }
  ],
  "pagination": { "page": 1, "per_page": 5, "total": 2210, "has_more": true, "mode": "flat" }
}

Result fields

Field	Type	Description
`id`	integer	Copyfy ad id.
`ad_archive_id`	string or null	Meta Ad Library id.
`page_name`	string	Facebook page that runs the ad (third-party content).
`status`	string	`active` or `inactive`.
`media_type`	string	`video`, `image`, `carousel`, `dco`, or `dpa`.
`headline`	string or null	Ad headline, truncated to 200 characters (third-party content).
`ad_text`	string or null	Ad copy, truncated to 500 characters (third-party content).
`cta`	string or null	Call-to-action label, spelled like the `ctas` filter values (`Shop Now`, not `Shop now`).
`landing_url`	string or null	Page the ad links to.
`image_url`	string or null	Ad image, or the thumbnail of a video ad. Videos are never returned: open `ad_library_url` to watch them.
`ad_library_url`	string or null	The ad in the Meta Ad Library.
`started_at`	string	Date the ad started.
`last_seen_at`	string	Date the ad was last seen running.
`active_days`	integer	Days from `started_at` to today for a running ad, or to `last_seen_at` for a stopped ad.
`is_partnership`	boolean	Partnership (branded content) ad.
`shop`	object or null	`id`, `name`, `domain`, `country`, and `active_ads` of the store. Pass `shop.id` to `get_shop`.
`dashboard_url`	string or null	The store’s page in Copyfy.

pagination.mode is grouped_by_shop when results show one ad per store (with sort_by: "recommended"), and then pagination.matching_shops counts the stores. Otherwise it is flat. As with search_shops, an empty result with an app or store creation date filter includes a notice. If the page exceeds 64 KiB, the last items are dropped and the result includes "truncated": true.

Get started

Connect a client

Account

Tools reference

Guides

Help

Arguments

Example

Result fields

​Arguments

​Example

​Result fields

Arguments

Example

Result fields