Ads · MCP TOOL

get_winning_ads

Rank creatives by the heuristic winning score.

Set up your assistant · Authentication and errors

When to use it

Discover long-running creatives using longevity, reach and advertiser commitment, not measured return on ad spend. Uses winning order and defaults to active creatives linked to an app.

Parameters

Name	Type	Required	Default	Allowed values	Description
`adSource`	string	No	`"all"`	meta, google, all	network
`appId`	string	No	`—`	—	"ios:284882215", "android:com.example.app", or a bare id together with `source` Minimum length: 1. Maximum length: 210.
`categories`	string[]	No	`—`	—	categories of the advertised app Maximum items: 20. Item minimum length: 1. Item maximum length: 80.
`countries`	string[]	No	`—`	—	ISO-2 reach countries Maximum items: 50. Item minimum length: 2. Item maximum length: 2.
`mediaType`	string	No	`—`	image, video, carousel, text, all	Creative media format.
`hasApp`	boolean	No	`—`	—	only creatives linked to a catalog app (default true)
`minScore`	number	No	`—`	—	Minimum heuristic winning score. Minimum: 0. Maximum: 100.
`minLongevity`	integer	No	`—`	—	Minimum observed creative longevity in days. Minimum: 0.
`minAppRevenue`	number	No	`—`	—	Minimum linked app modeled revenue (USD); paid plans only. Minimum: 0.
`status`	string	No	`"active"`	active, inactive, all	Delivery status.
`view`	string	No	`"compact"`	compact, full	Compact summaries or full creative records.
`limit`	integer	No	`20`	—	Maximum number of results requested. Minimum: 1. Maximum: 50.
`cursor`	integer	No	`0`	—	Zero-based offset; use the returned nextCursor to continue. Minimum: 0.
`after`	string	No	`—`	—	Opaque keyset token from nextAfter; replaces the offset when provided. Minimum length: 1. Maximum length: 1024.

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 winning video creatives advertising games.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_winning_ads",
    "arguments": {
      "categories": [
        "Games"
      ],
      "mediaType": "video",
      "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

Plan	Calls per tool / day	All tools / week
Free	5	50
Basic	100	700
Pro	300	2,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 get_winning_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.