Meta Ad Library search
Meta Ad Library search: inspect inputs, ad fields, pagination and limits, then run a local simulated request.
Copy the agent prompt manually
What this capability does
Meta Ad Library search uses /v1/meta/ads/search; GET returns data.items with ad objects.
This is a local simulation. Program-generated samples are not live platform data and do not establish provider availability.
- Capability: meta.ads.search
- Pagination: use the signed cursor from the response and request each page explicitly.
Input contract
Inspect meanings, examples and conditional rules for the selected method. view and fields control the response without changing the TEST unit price.
- Only send fields defined for this method; unknown fields are rejected before execution.
| Method | Field | Type | Requirement | Meaning | Enum or bound | Example |
|---|---|---|---|---|---|---|
| GET | query | string | Required | Search terms | — | "running shoes" |
| GET | region | string | Optional / conditional | Only ads delivered in this country or region, by its two-letter code; all of them when left out | — | — |
| GET | sort | string | Optional / conditional | By impressions, highest first, or newest first | ["popular","latest"] | — |
| GET | type | string | Optional / conditional | Only image ads or only video ads; all of them when left out | ["image","video"] | — |
| GET | cursor | string | Optional / conditional | The `next_cursor` of the previous page. A new page is a new call. | — | — |
| GET | view | string | Optional / conditional | How much of each item: compact (the most used fields, long text cut short), standard, or full (adds `ext`). | ["compact","standard","full"] | — |
| GET | fields | array | Optional / conditional | Return only these fields of each item, by path (`author.name`). | maxItems: 64 | — |
Try it locally
Use demo to inspect the fields, then explicitly select simulated with a customer test key to exercise settlement. Never put a customer key in a URL.
{
"capability": "meta.ads.search",
"method": "GET",
"params": {
"query": "running shoes"
}
}Output fields and interpretation
The ad object permits missing or null values; do not replace missing measurements with zero. This table shows the main structure; the object reference covers nested fields.
| Field | Type | Meaning | Source scope |
|---|---|---|---|
| id | string | null | ID; pass it unchanged to the ad's get endpoint | Meta Ad Library |
| url | string | null | The ad's page in the platform's ad library | Meta Ad Library |
| format | string | null | Format of the creative; other is a format of the platform's own | Meta Ad Library |
| title | string | null | Headline | Meta Ad Library |
| text | string | null | Body text | Meta Ad Library |
| landing_url | string | null | Where a click on the ad leads (standard view and up) | Meta Ad Library |
| advertiser | object | null | Advertiser | Meta Ad Library |
| advertiser.id | string | null | Advertiser ID | Meta Ad Library |
| advertiser.name | string | null | Advertiser's name | Meta Ad Library |
| advertiser.url | string | null | The advertiser's page on the platform (standard view and up) | Meta Ad Library |
| advertiser.avatar_url | string | null | The advertiser's picture or logo (standard view and up) | Meta Ad Library |
| images | array | null | Addresses of the ad's images (standard view and up) | Meta Ad Library |
| videos | array | null | Addresses of the ad's videos; they expire (full view) | Meta Ad Library |
| first_shown_at | string | null | When the ad was first shown | Meta Ad Library |
| last_shown_at | string | null | When the ad was last shown; for an ad still running, when the platform last saw it | Meta Ad Library |
| approximate | array | null | Which numbers of this item are approximate or lower bounds; absent when all are exact | Meta Ad Library |
| approximate[].field | string | null | Path of the field, such as metrics.views | Meta Ad Library |
| approximate[].kind | string | null | Approximate, or a lower bound | Meta Ad Library |
| ext | object | — | Meta Ad Library |
| ext.format_label | string | null | What the platform itself calls this ad format, as it words it (full view) | Meta Ad Library |
| ext.cta | string | null | Text of the call-to-action button (full view) | Meta Ad Library |
| ext.active | boolean | null | Whether the ad is running now (full view) | Meta Ad Library |
| ext.platforms | object | null | Where it is delivered: a yes or no for each platform (full view) | Meta Ad Library |
| ext.platforms.facebook | boolean | null | Whether it is delivered on Facebook (full view) | Meta Ad Library |
| ext.platforms.instagram | boolean | null | Whether it is delivered on Instagram (full view) | Meta Ad Library |
| ext.platforms.messenger | boolean | null | Whether it is delivered on Messenger (full view) | Meta Ad Library |
| ext.platforms.audience_network | boolean | null | Whether it is delivered on the Audience Network (third-party apps and sites) (full view) | Meta Ad Library |
| ext.platforms.threads | boolean | null | Whether it is delivered on Threads (full view) | Meta Ad Library |
| ext.platforms.whatsapp | boolean | null | Whether it is delivered on WhatsApp (full view) | Meta Ad Library |
| ext.cards | array | null | Each card of a carousel or of an ad with several versions; empty for an ad of one image or one video (full view) | Meta Ad Library |
| ext.cards[].title | string | null | The card's headline (full view) | Meta Ad Library |
| ext.cards[].text | string | null | The card's body text (full view) | Meta Ad Library |
| ext.cards[].landing_url | string | null | Where a click on the card leads (full view) | Meta Ad Library |
| ext.cards[].image_url | string | null | The card's image (full view) | Meta Ad Library |
| ext.cards[].video_url | string | null | The card's video; it expires (full view) | Meta Ad Library |
Limits and checks
A successful request does not establish full coverage. Preserve the request ID, observation time, parameters and cursor, and inspect the returned items before analysis.
Local simulation uses TEST credits only. Real provider calls, real payments and external email are disabled. Historical reference-site prices are not DataNavoAPI prices.
- Verify media URLs, counts and optional fields individually.
Clear inputs. Inspectable output.
Each click runs a local fixture. Advanced JSON inputs are checked against the selected method. Editing does not execute a request.
Copying does not execute. CLI quote is read-only and needs a local customer TEST key. Configure MCP in demo mode first. GET and POST batches both return only fictional local fixtures.
Download contract example (no execution) ↗For TEST budgets, Key scopes or failure scenarios, open the account console. Customer sandbox ↗