Ads in the Meta Ad Library that match a keyword, with the advertiser's Instagram handle, followers and verification when the advertiser has one. Each row is one ad with its copy, creatives, dates and status.
| parameter | type | description |
|---|---|---|
| query | string, required | The keyword, hashtag, place, id or URL this endpoint reads. |
| limit | integer | Items per page, up to 50 synchronously. Above that the call becomes a job. |
| cursor | string | meta.next_cursor from the previous page. |
| fresh | boolean | Skip the stored copy and read live, at the same price. |
| fields | string | Comma-separated field paths to keep. |
| format | json, csv | CSV flattens each item to one row. |
3 credits per ad. Failed calls are never charged, and empty results are free up to 25 a day. Stored copies are refreshed every 3 hours.
A page of ads. Each row carries the ad's id and Ad Library URL, its text and title, the call to action and landing URL, whether it is active, start and end dates, the platforms it runs on, image and video URLs, and the advertiser with its Instagram handle, follower count and verification when the Page has an Instagram account linked.
Reach and spend are passed through when the Ad Library publishes them; for most commercial ads they are null. Political and issue ads are the ones that carry them.
curl "https://api.instadata.dev/v1/instagram/ads-search?query=running%20shoes&limit=10" \ -H "Authorization: Bearer ik_live_..."
{
"data": [ … ],
"meta": { "count": …, "limit": …, "next_cursor": "…" },
"request_id": "req_01J…"
} | field | type | note |
|---|---|---|
| id | string | The Ad Library archive id. |
| url | string | The ad's page in the Meta Ad Library. |
| text | string|null | Primary ad copy. |
| title | string|null | Headline, when the format has one. |
| cta | string|null | Call-to-action type, e.g. SHOP_NOW. |
| link_url | string|null | Landing URL. |
| is_active | boolean|null | Whether the ad is currently running. |
| started_at | string|null | ISO 8601 start date. |
| ended_at | string|null | ISO 8601 end date; null while running. |
| platforms | string[]|null | Where the ad is delivered: instagram, facebook, messenger, audience_network. |
| advertiser | object | { handle, name }: the Facebook Page id and name behind the ad. |
| object | { handle, url, followers, verified } of the Page's linked Instagram account; nulls when none is linked. | |
| page | object | { alias, category, likes } of the Facebook Page. |
| images | string[]|null | Creative image URLs. |
| videos | string[]|null | Creative video URLs. |
| reach | number|null | EU reach estimate when published. |
| spend | number|string|null | Spend range when published, mostly on political ads. |
Each ad row costs 3 credits, reflecting its upstream price. An empty result is free up to the daily allowance.
Rows carry every placement the ad runs on. Filter on the platforms field if you only want ads delivered on Instagram; most multi-placement ads include it.
The keyword to search the Ad Library for.
No. The handle, follower count and verification come from the Instagram account linked to the advertiser's Facebook Page. Pages with no linked account return nulls in the instagram object.
They are passed through when the Ad Library publishes them, which is mainly for political and issue ads and EU reach reporting. On most commercial ads both are null.
3 credits per ad returned. Failed calls cost nothing and empty results are free up to the daily allowance.