Facebook Ad Search

Name: Facebook Ad Search
Price: 0.0011 USD
Availability: InStock
Author: Facebook

https://api.sandbase.ai/v1/api/facebook/ads-search

Search the Meta Ad Library by keyword and get matching ads (advertiser, creative text, CTA, platforms, and run dates) with cursor pagination.

Try this API Get API key

Price: $0.0011USD / call
Method: POST
Response: JSON
Parameters: 1 required · 10 optional

Production route

Try the model

Playground

Open playground

Input

Query(string)

Keyword to search the Meta Ad Library for (e.g. "protein powder").

AdType(string)

Restrict to all ads (default) or only political and issue ads. Allowed values: all, political_and_issue_ads.

Cursor(string)

Opaque pagination cursor from a previous response's nextCursor.

SortBy(string)

Sort order: impressions (highest first, the default) or recent (most recent). Allowed values: impressions, recent.

Status(string)

Ad status filter. Allowed values: ALL, ACTIVE, INACTIVE.

Country(string)

Two-letter country code to scope results. Omit for all countries.

EndDate(string)

Filter to ads with impressions on or before this date, in YYYY-MM-DD format.

MediaType(string)

Creative media type filter. Allowed values: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE.

StartDate(string)

Filter to ads with impressions on or after this date, in YYYY-MM-DD format.

SearchType(string)

Match mode for the query: loose keyword match (keyword_unordered, the default) or exact phrase (keyword_exact_phrase). Allowed values: keyword_unordered, keyword_exact_phrase.

RequireFields(array)

Optional; omit it and routing is unchanged, with the cheapest source serving. Name the output fields this request must be able to return, for example `totalResults`, and it is served only by a source that returns every one of them. Fields you do not name are still returned whenever the serving source has them. This can raise your price: when the cheapest source cannot return a named field, a dearer source serves, and you are quoted and charged its price. A named field can still be absent on an ad that genuinely lacks it. Naming a combination that no single source returns together is refused as invalid input, with no charge.

OutputReady

Your output will appear here

Complete the inputs, then click Run.

Model card

Specifications

Pricing

Base price: $0.0011 / run

Request & response

Method: POST
Request body: application/json
Response: application/json
Execution: sync

Parameters

query: string · required
adType: string (all, political_and_issue_ads) · optional
cursor: string · optional
sortBy: string (impressions, recent) · optional
status: string (ALL, ACTIVE, INACTIVE) · optional
country: string · optional
endDate: string · optional
mediaType: string (ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE) · optional
startDate: string · optional
searchType: string (keyword_unordered, keyword_exact_phrase) · optional
requireFields: array · optional

Access

Provider: Facebook
API: Platform API
Base URL: https://api.sandbase.ai
Endpoint: /v1/api/facebook/ads-search
Authentication: Bearer API key

API README

Facebook Ad Search API

Search the Meta Ad Library by keyword and get matching ads (advertiser, creative text, CTA, platforms, and run dates) with cursor pagination.

Request

curl -X POST "https://api.sandbase.ai/v1/run" \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "facebook/ads-search", "query": "nike", "country": "US", "searchType": "keyword_exact_phrase"}'

The result is returned in outputs[0].data. A lookup that finds nothing still succeeds and returns found: false.

Parameters

Name	Type	Required	Description
`query`	string	Yes	Keyword to search the Meta Ad Library for (e.g. "protein powder").
`adType`	string	No	Restrict to all ads (default) or only political and issue ads. One of: `all`, `political_and_issue_ads`.
`country`	string	No	Two-letter country code to scope results. Omit for all countries.
`cursor`	string	No	Opaque pagination cursor from a previous response's nextCursor.
`endDate`	string	No	Filter to ads with impressions on or before this date, in YYYY-MM-DD format.
`mediaType`	string	No	Creative media type filter. One of: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`.
`requireFields`	array	No	Optional; omit it and routing is unchanged, with the cheapest source serving. Name the output fields this request must be able to return, for example `totalResults`, and it is served only by a source that returns every o
`searchType`	string	No	Match mode for the query: loose keyword match (keyword_unordered, the default) or exact phrase (keyword_exact_phrase). One of: `keyword_unordered`, `keyword_exact_phrase`.
`sortBy`	string	No	Sort order: impressions (highest first, the default) or recent (most recent). One of: `impressions`, `recent`.
`startDate`	string	No	Filter to ads with impressions on or after this date, in YYYY-MM-DD format.
`status`	string	No	Ad status filter. One of: `ALL`, `ACTIVE`, `INACTIVE`. Default `"ACTIVE"`.

Pricing

Billed at the actual cost of each call, usually $0.0011 per request. A call can cost more when the first data source fails and another one answers. Failed calls are not charged. Lookups that find nothing and searches with no results are billed at their actual cost, which is often lower and can be $0.

Start building

Send your first request

Platform API endpoint with unified authentication and usage tracking.

Production API

Platform API endpoint

https://api.sandbase.ai/v1/api/facebook/ads-search

Authorization header

Authorization: Bearer $SANDBASE_API_KEY

# The quoted heredoc keeps Unicode and shell metacharacters unchanged.
result=$(curl --fail-with-body --silent \
  -X POST "https://api.sandbase.ai/v1/api/facebook/ads-search" \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'SANDBASE_JSON'
{
  "query": "nike",
  "status": "ACTIVE",
  "country": "US",
  "searchType": "keyword_exact_phrase"
}
SANDBASE_JSON
)
printf '%s\n' "$result"

Explore more

Related APIs

All APIs

API	Price	Response	Released
Facebook Ad SearchThis API `Facebook`	From $0.0011 per call	JSON	Oct 31, 2026
Facebook Ad Details `Facebook`	From $0.0012 per call	JSON	Oct 31, 2026
Facebook Ad Creative Details `Facebook`	From $0.0046 per call	JSON	Oct 31, 2026
Facebook Ad Transcript `Facebook`	From $0.0012 per call	JSON	Oct 31, 2026
Facebook Company Ads `Facebook`	From $0.0011 per call	JSON	Oct 31, 2026
Facebook Event Details `Facebook`	From $0.0012 per call	JSON	Oct 31, 2026

Questions

FAQ

How do I use the Facebook Ad Search API?

Send a POST request to https://api.sandbase.ai/v1/api/facebook/ads-search with your SandBase API key in the Authorization header (Bearer) and the parameters as a JSON body. You can also try it in the Playground on this page without writing code.

How much does the Facebook Ad Search API cost?

From $0.0011 per call, billed from your SandBase balance. You are only charged for calls you make; there is no subscription.

What parameters does the Facebook Ad Search API accept?

Required: query (string). Optional: adType (one of all, political_and_issue_ads), cursor (string), sortBy (one of impressions, recent), status (one of ALL, ACTIVE, INACTIVE), country (string) and endDate (string) and 4 more. The Parameters table and the Playground on this page list every field.

What does the Facebook Ad Search API return?

A JSON response returned in the same HTTP request (synchronous).

Do I need a Facebook developer account or API key?

No. Facebook Ad Search runs through SandBase, so one SandBase API key covers this endpoint and every other API and model in the catalog. You do not need to apply for Facebook API access separately.