> ## Documentation Index > Fetch the complete documentation index at: https://docs.copyfy.io/llms.txt > Use this file to discover all available pages before exploring further. # search_ads > Search Meta ads run by Shopify stores, by format, call to action, run time, reach, and store filters. 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`](/tools/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`](/errors#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: ```json Tool call theme={null} { "name": "search_ads", "arguments": { "niches": ["Beauty"], "media_types": ["video"], "status": "active", "ad_started_between": { "from": "2026-08-24" }, "sort_by": "reach", "per_page": 5 } } ``` ```json Result (trimmed) theme={null} { "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`](/tools/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`](/tools/search-shops#result-fields), 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`.