credits_used in the response states what the call cost.
In apps that support MCP Apps, such as Claude and ChatGPT, the results also appear as a carousel of ad cards: the ad video or image, status, days running, ad copy, and Open in Copyfy and Ad Library buttons. The JSON is the same in every client.
Arguments
Store filters apply to the store that runs the ad. Here,query matches ad copy, Facebook page names, and store names.
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:
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
Result (trimmed)
query keeps the ads that contain every one of its words, as whole words. With sort_by: "recommended", the stores whose ad matches the words most closely come first. Other sorts show one ad per identical copy of a store, so a page can hold fewer ads than per_page.
Result fields
Age, gender, and EU reach breakdowns from the Meta Ad Library are not returned: Copyfy does not collect them.
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 call returns result_too_large without charging a credit or dropping items. Narrow the filters to recover later matches, or restart pagination with a smaller per_page and deduplicate earlier results. The 20-page limit still applies, so a smaller page size reduces the reachable results.