API reference · Facebook

facebook/ads-search

Integrate this model through SandBase's unified API, with production-ready schemas and examples.

APISynchronousOpen model

Production endpoint

Send your first request

OpenAI-compatible endpoint with unified authentication and usage tracking.

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

Model IDfacebook/ads-search

Input Schema

11 parameters · 1 required · 10 optional

Parameter	Type	Required	Description
`query`	string	Required	Keyword to search the Meta Ad Library for (e.g. "protein powder").
`adType`	string	Optional	Restrict to all ads (default) or only political and issue ads. · Options: all, political_and_issue_ads allpolitical_and_issue_ads
`cursor`	string	Optional	Opaque pagination cursor from a previous response's nextCursor.
`sortBy`	string	Optional	Sort order: impressions (highest first, the default) or recent (most recent). · Options: impressions, recent impressionsrecent
`status`	string	Optional	Ad status filter. · Options: ALL, ACTIVE, INACTIVE · Default: "ACTIVE" ALLACTIVEINACTIVE
`country`	string	Optional	Two-letter country code to scope results. Omit for all countries.
`endDate`	string	Optional	Filter to ads with impressions on or before this date, in YYYY-MM-DD format.
`mediaType`	string	Optional	Creative media type filter. · Options: ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE ALLIMAGEVIDEOMEMEIMAGE_AND_MEMENONE
`startDate`	string	Optional	Filter to ads with impressions on or after this date, in YYYY-MM-DD format.
`searchType`	string	Optional	Match mode for the query: loose keyword match (keyword_unordered, the default) or exact phrase (keyword_exact_phrase). · Options: keyword_unordered, keyword_exact_phrase keyword_unorderedkeyword_exact_phrase
`requireFields`	string[]	Optional	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.

Output Schema

Field	Type	Description
`id`	string	Unique identifier for the generation task
`status`	string	Task status: pending, running, completed, failed, timeout
`model`	string	Model used for the generation
`outputs`	array	Array of output items
`outputs[].url`	string	URL of the generated artifact
`outputs[].content_type`	string	MIME type (e.g. image/png, video/mp4)
`error`	object \| null	Error details if failed, null on success
`error.type`	string	Machine-readable error type code
`error.message`	string	Human-readable error description

Code Examples

Ready-to-run snippets

const apiKey = process.env.SANDBASE_API_KEY;
const response = await fetch("https://api.sandbase.ai/v1/api/facebook/ads-search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "nike",
    "status": "ACTIVE",
    "country": "US",
    "searchType": "keyword_exact_phrase"
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

← Back to Facebook Ad Search