Search the Ad Library

Searches the Meta Ad Library by query and/or one pageId, in country (default US), and returns each ad with an image: page, copy, call to action, start date and image urls (signed, expiring within days). Ads without an image are counted in withoutImages. Page with cursor.

GET

/v1/brands/{brandId}/ad-library/ads

Authorization

bearerAuth

headerAuthorizationBearer <token>

An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.

Path Parameters

brandId*integer

The brand the request acts on. Every brand-scoped resource lives under its brand.

Query Parameters

query*string

An advertiser's website domain, such as "triplewhale.com", to get that advertiser's own ads; a name also brings other advertisers' ads. Or keywords for an offer. With pageId, * lists every ad of that page.

Length1 <= length <= 200

pageId?string

One Facebook page id, from an earlier result, to see only that advertiser's ads.

Match^\d{3,25}$

country?string

Two-letter country the ads ran in. Defaults to US.

Match^[A-Z]{2}$

activeOnly?boolean

Only ads running now. Defaults to true; an ad that has run for months is usually a winner.

limit?integer

Ads per page, 1-24. Defaults to 12.

Range1 <= value <= 24

cursor?string

nextCursor from the previous page.

Length1 <= length <= 500

forRound?boolean

true when you search for references for a round of ads you are making: the user does not see the results. Omit it when the user asked to see other advertisers' ads.

Response Body

Search the Ad Library

application/json

response

ads*array<>

withoutImages*integer

Ads on this page that carried no image, and are left out.

Range-9007199254740991 <= value <= 9007199254740991

nextCursor*string|null

[key: string]?unknown

curl -X GET "https://example.com/v1/brands/0/ad-library/ads?query=string" \  -H "Authorization: Bearer koast_sk_..."

{  "ads": [    {      "adArchiveId": "string",      "pageId": "string",      "pageName": "string",      "format": "string",      "text": "string",      "title": "string",      "ctaText": "string",      "linkUrl": "string",      "active": true,      "startedAt": "string",      "platforms": [        "string"      ],      "libraryUrl": "string",      "images": [        {          "url": "string",          "previewUrl": "string",          "property1": null,          "property2": null        }      ],      "property1": null,      "property2": null    }  ],  "withoutImages": -9007199254740991,  "nextCursor": "string",  "property1": null,  "property2": null}

Required scope: read. CLI: koast search-ad-library, see Ad Library commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.