Search Ads by Name
search_ads_by_namesRead-only
Search for ads by name in the Metadata platform library, with pagination.
**USE THIS TOOL WHEN THE USER ASKS ABOUT:**
- Ad details, information, or status
- Finding an ad by name
- Getting ad IDs
- Checking if an ad exists
- Looking up ad creative assets (images, thumbnails)
- Ad type or channel information
- Any question containing words like: "ad", "creative", "show me", "find", "search", "image"
SEARCH FEATURES:
- Partial, case-insensitive matching on ad names
- Returns ad ID, name, channel type, ad type, status, and image URLs
- Three-state status filter via the `status` param (default
`"active"`, preserves the prior active-only behaviour):
* `"active"` → active ads only
* `"archived"` → archived (soft-deleted) ads only; use
this to find an ad id for `unarchive_ad`
* `"all"` → both active and archived in one response
PAGINATION:
- Supports `page` and `size` parameters (defaults: page=0, size=25).
- Page numbering starts at 0.
- Recommended size: 5-25 to keep responses LLM-friendly. Use up
to 100 only when the caller needs a wider sweep — large pages
can blow your context budget.
- Returned `total_elements` and `total_pages` are taken from the
platform's PageResponse so callers can drive a paginator.
- When `ad_names` carries multiple entries, the platform endpoint
accepts only ONE name per request — this tool fires one paged
request per name and merges results. `page`/`size` apply
PER-NAME, `total_elements` is the SUM across names, and
`total_pages` is the MAX across names. Single-name searches
get clean pagination semantics; multi-name is best-effort.
PARAMETERS:
- ad_names: Array of ad name strings to search for (required, ≥1)
- page: Zero-based page index (optional, default 0)
- size: Results per page (optional, default 25)
- sort: Spring sort clause (optional, default "createdDate,desc";
also valid: "id,desc", "name,asc", etc.)
- status: "active" (default) / "archived" / "all". Pick the
bucket you want; "archived" is the unarchive
discovery path, "all" is the rare both-buckets case.
RETURNS:
{
"found_ads": [
{
"id": 190084,
"name": "AI_Marketing_Audit_Q4_2025_Demo_LI_LI",
"channelType": "LINKEDIN",
"adType": "IMAGE",
"completionStatus": "COMPLETED",
"status": true,
"thumbnail": "https://...",
"imageUrl": "https://..."
}
],
"missing_names": ["NonExistent"],
"total_found": 1,
"page": 0,
"size": 25,
"sort": "createdDate,desc",
"total_elements": 1,
"total_pages": 1
}
CHANNEL TYPES: LINKEDIN, FACEBOOK, INSTAGRAM, GOOGLE, REDDIT, MICROSOFT_ADS
AD TYPES: IMAGE, VIDEO, CAROUSEL, TEXT
STATUS: true (active) or false (inactive)Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Zero-based page index (default: 0). Page numbering starts at 0. | |
| size | No | Results per page (default: 25, recommended max: 25). Larger windows blow LLM token budgets — only request more when the caller actually needs it. | |
| sort | No | Spring sort clause, e.g. 'createdDate,desc' (default), 'id,desc', or 'name,asc'. | |
| status | No | Which status bucket to return. 'active' (default) is the prior active-only behaviour. 'archived' returns ONLY archived (soft-deleted) ads, which is what you need to find an ad's id for unarchive_ad. 'all' returns both active and archived in one response. Maps to the platform's status query param semantics (Set<Boolean>): active=true, archived=false, all=omit. | active |
| ad_names | Yes | Array of ad names or partial names to search for (case-insensitive, partial matching) |