# Meta Ad Library API guide ## Choose a Meta Ad Library operation Start with the object your task needs. The groups below use the current catalogue; open an endpoint to check accepted identifiers, filters, price and availability before retrieving. ### Other operations - [Ad details](https://www.monocrawl.com/docs/endpoints/meta_ads/ad) — One Meta ad by archive id: full creative snapshot, platforms, run dates, and spend/reach where the Ad Library discloses them. - [Company ads](https://www.monocrawl.com/docs/endpoints/meta_ads/company-ads) — Ads currently or previously running for one advertiser: creative body, title, CTA, link, images/videos, platforms and active state. Paged by cursor. ### Transcripts - [Ad transcript](https://www.monocrawl.com/docs/endpoints/meta_ads/ad-transcript) — The spoken words of a Meta video ad as text. transcript is null when the video has no speech — that is the honest answer, not an error. ### Search and discovery - [Ad search](https://www.monocrawl.com/docs/endpoints/meta_ads/search) — Keyword search across the Meta Ad Library: matching ads with advertiser page, creative snapshot and platforms. Paged by cursor. - [Advertiser search](https://www.monocrawl.com/docs/endpoints/meta_ads/search-companies) — Search Meta Ad Library advertisers: page id, name, category, likes, verification and Instagram handle. The page id feeds meta_ads/company-ads. ## Check fields and collection limits Use the endpoint’s declared parameters and returned continuation. Filters from another platform do not automatically apply here. Preserve source identifiers, URLs and warnings; a successful page does not establish complete history. Published response schemas identify whether they come from a reviewed shaper or observed response shapes. Agents can use `get_endpoint` for the current contract and `get_docs` with topic `platforms/meta_ads` to read this page. The [coverage guide](https://www.monocrawl.com/docs/data-availability) explains nulls and partial results, and the [production guide](https://www.monocrawl.com/docs/production-checklist) covers budgets and recovery. ## Endpoint reference ## meta_ads/ad `GET /v1/meta_ads/ad` One Meta ad by archive id: full creative snapshot, platforms, run dates, and spend/reach where the Ad Library discloses them. *Ad details* | Parameter | Required | Description | | --- | --- | --- | | `id` | yes | Ad archive id from a search or company-ads result. — e.g. `1702938977100376` | | `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` | ### Useful optional inputs - `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees. **Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/meta_ads/ad?id=1702938977100376" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "body": "example", "cta": "example", "display_format": "example", "ended_at": "2026-09-01T12:00:00Z", "id": "example", "images": [], "is_active": false, "link_url": "https://example.com/example", "page": { "id": "example", "name": "example" }, "platform": "example", "publisher_platforms": [ "example" ], "started_at": "2026-09-01T12:00:00Z", "title": "example", "videos": [] } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/meta_ads/ad#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/meta_ads/ad.json) ## meta_ads/ad-transcript `GET /v1/meta_ads/ad-transcript` The spoken words of a Meta video ad as text. transcript is null when the video has no speech — that is the honest answer, not an error. *Ad transcript* | Parameter | Required | Description | | --- | --- | --- | | `id` | yes | Ad archive id of a VIDEO ad. — e.g. `4439810673014351` | | `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` | ### Useful optional inputs - `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees. **Cost:** 5 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/meta_ads/ad-transcript?id=4439810673014351" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "platform": "meta_ads", "id": "example-ad", "transcript": "Illustrative spoken words.", "has_transcript": true } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/meta_ads/ad-transcript#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/meta_ads/ad-transcript.json) ## meta_ads/company-ads `GET /v1/meta_ads/company-ads` Ads currently or previously running for one advertiser: creative body, title, CTA, link, images/videos, platforms and active state. Paged by cursor. *Company ads* | Parameter | Required | Description | | --- | --- | --- | | `pageId` | yes | Facebook page id from meta_ads/search-companies (or pass companyName instead). — e.g. `15087023444` | | `companyName` | no | Company name — alternative to pageId. | | `country` | no | Two-letter country code or ALL. — e.g. `ALL` | | `status` | no | ACTIVE, INACTIVE or ALL. Accepted values: ACTIVE, INACTIVE, ALL. Case, spaces, hyphens and underscores are interchangeable. | | `media_type` | no | ALL, IMAGE or VIDEO. Accepted values: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE. Case, spaces, hyphens and underscores are interchangeable. | | `sort_by` | no | e.g. total_impressions. Accepted values: total_impressions, relevancy_monthly_grouped. Case, spaces, hyphens and underscores are interchangeable. | | `start_date` | no | YYYY-MM-DD. | | `end_date` | no | YYYY-MM-DD. | | `cursor` | no | Opaque cursor from the previous page. | | `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` | ### Useful optional inputs - `media_type`: Restrict returned content to the supported media types for your task. Filtering can return fewer results; the normal endpoint price still applies. - `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ. - `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees. **Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/meta_ads/company-ads?pageId=15087023444" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "cursor": null, "dropped": 0, "items": [ { "body": "example", "cta": "example", "display_format": "example", "ended_at": "2026-09-01T12:00:00Z", "id": "example", "images": [], "is_active": false, "link_url": "https://example.com/example", "page": { "id": "example", "name": "example" }, "platform": "example", "publisher_platforms": [ "example" ], "started_at": "2026-09-01T12:00:00Z", "title": "example", "videos": [ {} ] } ] } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/meta_ads/company-ads#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/meta_ads/company-ads.json) ## meta_ads/search `GET /v1/meta_ads/search` Keyword search across the Meta Ad Library: matching ads with advertiser page, creative snapshot and platforms. Paged by cursor. *Ad search* | Parameter | Required | Description | | --- | --- | --- | | `query` | yes | Keyword to search ad creatives for. — e.g. `running shoes` | | `country` | no | Two-letter country code or ALL. | | `status` | no | ACTIVE, INACTIVE or ALL. Accepted values: ACTIVE, INACTIVE, ALL. Case, spaces, hyphens and underscores are interchangeable. | | `media_type` | no | ALL, IMAGE or VIDEO. Accepted values: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE. Case, spaces, hyphens and underscores are interchangeable. | | `ad_type` | no | e.g. all. | | `language` | no | Two-letter language code. — e.g. `EN` | | `sort_by` | no | e.g. total_impressions. Accepted values: total_impressions, relevancy_monthly_grouped. Case, spaces, hyphens and underscores are interchangeable. | | `start_date` | no | YYYY-MM-DD. | | `end_date` | no | YYYY-MM-DD. | | `cursor` | no | Opaque cursor from the previous page. | | `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` | ### Useful optional inputs - `media_type`: Restrict returned content to the supported media types for your task. Filtering can return fewer results; the normal endpoint price still applies. - `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ. - `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees. **Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/meta_ads/search?query=running%20shoes" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "cursor": null, "dropped": 0, "items": [ { "body": "example", "cta": "example", "display_format": "example", "ended_at": "2026-09-01T12:00:00Z", "id": "example", "images": [ "example" ], "is_active": false, "link_url": "https://example.com/example", "page": { "id": "example", "name": "example" }, "platform": "example", "publisher_platforms": [ "example" ], "started_at": "2026-09-01T12:00:00Z", "title": "example", "videos": [ {} ] } ] } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/meta_ads/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/meta_ads/search.json) ## meta_ads/search-companies `GET /v1/meta_ads/search-companies` Search Meta Ad Library advertisers: page id, name, category, likes, verification and Instagram handle. The page id feeds meta_ads/company-ads. *Advertiser search* | Parameter | Required | Description | | --- | --- | --- | | `query` | yes | Company or brand name. — e.g. `nike` | | `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` | ### Useful optional inputs - `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees. **Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key. ```bash curl "https://www.monocrawl.com/v1/meta_ads/search-companies?query=nike" \ -H "x-api-key: mn_your_key_here" ``` ### Response data Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed. ```json { "items": [ { "category": "example", "ig_handle": "example", "image": "https://example.com/example", "likes": 0, "name": "example", "page_id": "example", "platform": "example", "verified": false } ] } ``` [Field reference](https://www.monocrawl.com/docs/endpoints/meta_ads/search-companies#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/meta_ads/search-companies.json)