---
title: "search_ads_by_names. Metadata MCP tool reference"
url: https://metadata.io/developers/tools/search_ads_by_names
description: "Search for ads by name in the Metadata platform library, with pagination. Read tool on the Metadata MCP server, with its full JSON Schema."
source: metadata.io
---

# search_ads_by_names

Search for ads by name in the Metadata platform library, with pagination.

Read [creative](https://metadata.io/developers/tools/#cat-creative)

## What it does

## Arguments

| Argument | Type |   | Notes |
|---|---|---|---|
| `ad_names` | array | required | Array of ad names or partial names to search for (case-insensitive, partial matching) |
| `page` | integer |   | Zero-based page index (default: 0). Page numbering starts at 0. |
| `size` | integer |   | Results per page (default: 25, recommended max: 25). Larger windows blow LLM token budgets — only request more when the caller actually needs it. |
| `sort` | string |   | Spring sort clause, e.g. 'createdDate,desc' (default), 'id,desc', or 'name,asc'. |
| `status` | string |   | 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 semone of: `active`, `archived`, `all` |

## Request

**Request template, not a complete runnable example.** Replace placeholders, empty objects, arrays, and zero values with valid account-specific inputs. Read required fields and nested constraints in the full schema. Confirm the account, connected channels, and referenced assets before calling a write tool.

## Response

## Related

Other creative tools:

- [archive_ad](https://metadata.io/developers/tools/archive_ad) Destructive
- [create_update_carousel_ad](https://metadata.io/developers/tools/create_update_carousel_ad) Destructive
- [create_update_convo_ad](https://metadata.io/developers/tools/create_update_convo_ad) Destructive
- [create_update_document_ad](https://metadata.io/developers/tools/create_update_document_ad) Destructive
- [create_update_google_ads_ad](https://metadata.io/developers/tools/create_update_google_ads_ad) Destructive
- [create_update_image_ad](https://metadata.io/developers/tools/create_update_image_ad) Destructive
- [create_update_linkedin_message_ad](https://metadata.io/developers/tools/create_update_linkedin_message_ad) Destructive
- [create_update_microsoft_ads_ad](https://metadata.io/developers/tools/create_update_microsoft_ads_ad) Destructive

[Browse the tool catalog](https://metadata.io/developers/tools/) · [machine-readable index](https://metadata.io/developers/tools.json)