Skip to content
AppGazers

Ads · MCP TOOL

search_ads

Search stored Meta and Google creatives with typed filters.

Set up your assistant · Authentication and errors

When to use it

Research creatives with displayable media. Meta commercial coverage is EU/UK delivery; Google coverage comes from verified advertiser domains.

Parameters

NameTypeRequiredDefaultAllowed valuesDescription
limitintegerNo20—Maximum number of results requested. Minimum: 1. Maximum: 100.
countbooleanNo——Request an exact total when supported; broad or deep searches can still omit it.
cursorintegerNo0—Zero-based offset; use the returned nextCursor to continue. Minimum: 0.
afterstringNo——Opaque keyset token from nextAfter; replaces the offset when provided. Minimum length: 1. Maximum length: 1024.
searchstringNo——Search words or a supported store identifier. Minimum length: 1. Maximum length: 100.
idsstring[]No——Explicit resource IDs.
appIdstringNo——App identifier. Minimum length: 1.
advertiserIdstringNo——Advertiser identifier. Minimum length: 1.
developerstringNo——Publisher name or identifier supported by this search. Minimum length: 1. Maximum length: 200.
linkDomainstringNo——Advertised destination domain. Minimum length: 1. Maximum length: 200.
adSourcestringNo"all"meta, google, allAd network.
mediaTypestringNo—image, video, carousel, text, allCreative media format.
statusstringNo—active, inactive, allDelivery status.
activebooleanNo——Legacy active-delivery flag; prefer status.
hasAppbooleanNo——Filter by a link to a catalog app.
categoriesstring[]No——Store category IDs or names.
excludedCategoriesstring[]No——Categories to exclude.
countrystringNo——Two-letter storefront country code. Minimum length: 2. Maximum length: 2.
countriesstring[]No——Reach country codes.
excludedCountriesstring[]No——Reach country codes to exclude.
platformsstring[]No——Platform filters.
surfacesstring[]No——Meta delivery surfaces.
excludedSurfacesstring[]No——Meta delivery surfaces to exclude.
languagesstring[]No——Language filters.
minLongevityintegerNo——Minimum observed creative longevity in days. Minimum: 0.
maxLongevityintegerNo——Maximum observed creative longevity in days. Minimum: 0.
minReachintegerNo——Minimum observed reach. Minimum: 0.
minScorenumberNo——Minimum heuristic winning score. Minimum: 0. Maximum: 100.
startedAfterstring (date-time)No——Delivery start lower bound.
startedBeforestring (date-time)No——Delivery start upper bound.
endedAfterstring (date-time)No——Delivery end lower bound.
endedBeforestring (date-time)No——Delivery end upper bound.
minAppDownloadsnumberNo——Minimum linked app modeled downloads. Minimum: 0.
maxAppDownloadsnumberNo——Maximum linked app modeled downloads. Minimum: 0.
minAppRevenuenumberNo——Minimum linked app modeled revenue (USD); paid plans only. Minimum: 0.
maxAppRevenuenumberNo——Maximum linked app modeled revenue (USD); paid plans only. Minimum: 0.
sortBystringNo"newest"newest, start_date, oldest, end_date, longest, reach, winning, score, app_downloads, app_revenueResult ordering.
sortOrderstringNo—asc, descSort direction.
viewstringNo"full"compact, fullCompact summaries or full creative records.

Defaults and constraints come from the published Zod input schema. “—” means no schema default or no enum restriction. Use JSON values of the listed type; additional handler rules are described above.

Example prompts

  • Show Facebook’s active creatives, longest-running first.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_ads",
    "arguments": {
      "appId": "ios:284882215",
      "status": "active",
      "sortBy": "longest",
      "view": "compact",
      "limit": 5
    }
  }
}

Example result

Illustrative, abridged JSON-RPC result. Only selected fields are shown; empty arrays illustrate a response with no rows. These are not current catalog observations. Parse the JSON inside content[].text.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\":[]}"
      }
    ]
  }
}

Free vs paid results

Free keeps identities for rows 1–10 by absolute position, locks identities at 11+, and hides revenue estimates. Basic and Pro unlock these fields. Explicit ID lists keep their named identities.

Paid access does not fill coverage gaps or unknown values. Returned plan metadata and lock notes explain redaction where applicable. Read the full Free data policy.

Rate limits and usage credit

PlanCalls per tool / dayAll tools / week
Free550
Basic100700
Pro3002,500

Days reset at 00:00 UTC. The combined ISO week resets Monday at 00:00 UTC. Every served tool call counts, including cached reads. Failed or refused calls are released along with any charge. Compare plans.

After either allowance, Basic and Pro can opt in to pay $0.02 in usage credit per call to search_ads. A call exceeding both windows is charged once. Free is refused past its allowances; paid plans without opt-in or enough credit are also refused with HTTP 402 / JSON-RPC -32004.

Credential request throttles and, for live keyword work, store-work throttles also apply. Follow retry instructions in the error reference.