meta_ads_list_ads

List Meta Ads

Meta

Description

List ads for a Meta ad account with ad set filtering, status, name search, single/multi-ad lookup by ID, and pagination. Each ad includes a Landing URL when available (extracted from object_story_spec, link_url, or asset_feed_spec depending on ad format) and a URL Tags line exposing the ad's tracking-template string — the URL parameters (UTMs / custom click-tracking) Meta appends to the destination URL at click time, with {{macro}} placeholders preserved verbatim. The ad-level url_tags field wins when set; otherwise the response falls back to creative-level url_tags / template_url_spec. A "Landing Page URLs" summary lists every unique destination URL; a "URL Tags Audit" summary lists the distinct templates in use and names every ad with a destination URL but no tracking template — use these to audit UTM coverage across an account without reading every ad. Set include_assets=true to include resolved creative media URLs (adds latency for cache misses). Entities may include _stored_preferences, optionally recent activities, and optionally automated rules (set include_rules=true to see which rules affect each ad).

Read-onlyIdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_list_ads",
    "arguments": {
      "account_id": "123456789",
      "reason": "List ads"
    }
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required The ad account ID (with or without act_ prefix)minLength: 1
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (12)
NameTypeRequiredDescription
ad_id string Optional Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination.minLength: 1
ad_ids array Optional Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination.
adset_id string Optional Filter by ad set IDminLength: 1
search string Optional Search ads by name (case-insensitive partial match)minLength: 1
status array Optional Filter by configured ad status (user-set): ACTIVE, PAUSED, DELETED, ARCHIVED
effective_status array Optional Filter by Meta-computed serving status: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES, CAMPAIGN_PAUSED, ADSET_PAUSED, DISAPPROVED, PENDING_REVIEW, PENDING_BILLING_INFO, PREAPPROVED
limit integer Optional Number of ads per page (default: 20, max: 100)min: 1, max: 100
cursor string Optional Pagination cursor from previous responseminLength: 1
refresh boolean Optional Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data.
include_activities boolean Optional Include recent activity log (last 7 days of changes) for each entity
include_assets boolean Optional Include resolved creative asset URLs (asset_url, thumbnail_url, asset_type) for each ad. Uses cached GCS URLs when available.
include_rules boolean Optional Include automated rules (from adrules_library) that affect each entity

Examples

List all

{
  "account_id": "123456789",
  "reason": "List ads"
}

hopkin meta ads list --account 123456789

Filter by ad set

{
  "account_id": "123456789",
  "adset_id": "23842453456789",
  "reason": "List ads in ad set"
}

hopkin meta ads list --account 123456789 --adset 23842453456789

Filter by status

{
  "account_id": "123456789",
  "status": [
    "ACTIVE",
    "PAUSED"
  ],
  "reason": "List active/paused ads"
}

hopkin meta ads list --account 123456789 --status ACTIVE,PAUSED

Find disapproved / review-blocked

{
  "account_id": "123456789",
  "effective_status": [
    "DISAPPROVED",
    "WITH_ISSUES",
    "PENDING_REVIEW"
  ],
  "reason": "Surface ads blocked by review"
}

hopkin meta ads list --account 123456789 --effective-status DISAPPROVED,WITH_ISSUES,PENDING_REVIEW

Get by ID

{
  "account_id": "123456789",
  "ad_id": "23842453456789",
  "reason": "Get specific ad"
}

hopkin meta ads list --account 123456789 --ad 23842453456789

Get multiple by IDs

{
  "account_id": "123456789",
  "ad_ids": [
    "23842453456789",
    "23842453456790"
  ],
  "reason": "Get specific ads"
}

hopkin meta ads list --account 123456789 --ad-ids 23842453456789,23842453456790

Search by name

{
  "account_id": "123456789",
  "search": "Summer",
  "reason": "Find summer ads"
}

hopkin meta ads list --account 123456789 --search Summer

With asset URLs

{
  "account_id": "123456789",
  "include_assets": true,
  "reason": "List ads with creative assets"
}

hopkin meta ads list --account 123456789 --include-assets true