Read Meta ads data
meta_ads_readReads Meta ad accounts. action "list_tools" lists every operation of every router with its field names, flags and the router that executes it (get_tool_schema returns the input schema); it does not call Meta and is free. action "execute" runs one read: {"action":"execute","tool_name":"list_campaigns","arguments":{}}. Reads:
account_summary: The connected ad account: name, currency, status, lifetime spend.
list_pages: Facebook Pages that ads can run under.
list_campaigns: Campaigns in the ad account: configured and effective status, objective, budget. Deleted campaigns are not shown, archived only on request.
campaign_details: One campaign in full: settings, budget and its ad sets with a targeting summary, optionally its ads.
list_adsets: Ad sets across the whole ad account or one campaign (except deleted and archived by default): configured and effective status, budgets. Join with campaigns on campaign_id.
list_ads: Ads in the ad account, or in one campaign or ad set: status, effective status, creative.
ad_statuses: Statuses for a batch of ads in one request, so you do not have to guess what is already off.
list_images: Images in the ad account library, with the hashes that create_ad_creative takes.
list_videos: Videos in the ad account library, with the ids that create_video_creative takes.
list_creatives: Creatives already built in this ad account: what each one says, where it links and which picture it uses.
preview_ad: See the ad as it looks in the feed, drawn by Meta. Answers with a link for a person; no impressions and no spend.
upload_link: A page where a person adds creatives and sees the ones already in the library. Nothing is sent to Meta by this call.
read_landing_page: What a landing page says — headline, sections, numbers, prices, buttons and its language — to write ad texts from. Nothing is sent to Meta.
list_instagram_accounts: Instagram accounts this ad account can run ads from.
list_custom_audiences: Custom and lookalike audiences that Meta lists for this ad account, with size and whether they can be used.
search_targeting: Search Meta targeting options by words: interests, behaviors, demographics, life events, employers, job titles, schools, majors, locations and languages.
list_pixels: Meta pixels (datasets) this ad account can use, and when each last fired.
list_custom_conversions: Custom conversions of the ad account: event type, pixel and whether they still fire.
pixel_stats: Event counts of one pixel, by event and by hour, for up to the last 28 days.
ad_issues: Ads Meta rejected or holds with a delivery issue in running campaigns, with Meta's reasons, and ad sets that are Learning limited.
dashboard_data: The numbers behind performance_dashboard: spend, results, cost per result, link CTR and CPM against the previous period, by day and by campaign.
account_playbook: A skill for the assistant made from this ad account: what it sells, how campaigns are named, which result counts, targets, house rules, pitfalls and questions with real names.
analyze_wasted_spend: Classify the campaigns that spent in a window: wasted, below target, lead campaigns, learning or too little data.
analyze_audiences: Which age and gender groups the money goes to, what each of them brings, and where a result costs more than it does across the ad account.
analyze_placements: Which placements the money goes to — Feed, Stories, Reels, Audience Network and the rest — what each brings and where a result costs more than across the ad account.
detect_creative_fatigue: Score the active ads for creative fatigue: frequency, link CTR decline and how long they have been running.
ad_copy_brief: Everything needed to write new Meta ad texts for a campaign: its primary texts and headlines with spend, link CTR, results and cost per result, which ones beat the other texts beyond chance, the money they brought when payments are sent in, the landing pages and Meta's recommended text lengths, overall and by placement. The assistant writes the texts.
explain_anomaly: Explain why a metric changed — cost per result (CPA, cost per lead or purchase), ROAS, CTR, CPC, CPM, conversions — against the 30, 60 and 90 day baselines: which campaigns and ad sets moved it, at which funnel step, whether it is beyond chance, and what was edited in the ad account in those days.
optimize_budget: Recommend how to split a monthly budget pool across campaigns or ad sets. It changes nothing.
diagnose_funnel: Walk the funnel in order — tracking, revenue, traffic, conversion, spend — and stop at the first broken step.
browse_targeting: Browse a whole Meta targeting category: interests, behaviors, demographics, life events, industries, income or family statuses.
select_campaign_type: The order of tools that builds a campaign of a given type, and what it needs before it can be built.
copy_status: Check an asynchronous campaign copy: whether Meta finished it and what it produced.
app_performance: App promotion campaigns of this ad account: spend, installs and cost per install by campaign, ad set or ad, with the in-app events Meta reports for them.
list_promotable_apps: Mobile apps this ad account may advertise, with their store links and the events they report.
list_monitors: Monitors of this ad account: their conditions, status, last check and how often they triggered.
get_monitor_history: When a monitor triggered, on which campaigns, ad sets or ads, with what numbers, and whether an email went out.
test_monitor: Dry-run a monitor now: which campaigns, ad sets or ads would trigger and which are skipped, without recording or emailing.
list_scheduled_tasks: Scheduled briefs of this account and monitors of this ad account, with status, schedule and last run.
list_signals: What the watchdog found in this ad account and has not seen resolved.
run_watch_now: Run the watchdog over this ad account right now instead of waiting for its next pass.
list_pending_actions: Changes the watchdog and monitors prepared for approval: pauses and budget changes, with what each would do.
get_signal_briefing: One finding of the watchdog or a monitor: what was seen, since when, and the changes prepared for it.
get_opportunity_score: Meta's opportunity score for this ad account (0–100) and the recommendations Meta gives to raise it.
audience_details: One custom or lookalike audience in full: what it is built from, its size, its status and whether it can be used.
audience_adsets: Which ad sets use a custom or lookalike audience, with how many of their ads do.
pixel_details: One pixel (dataset) in full: its settings, when it last fired, and the checks Meta runs on it.
pixel_quality: How well the customer information sent with a pixel's server-side events can be matched to people, per event.
list_creative_ads: Ads that use one creative: id, name, status and where they sit.
list_business_pages: Facebook Pages owned by the business behind this ad account, and Pages it manages for clients.
activity_log: What was changed in this ad account and when: budgets, targeting, bids, statuses, schedules and new campaigns and ad sets.
list_experiments: A/B tests and lift studies that involve this ad account: what each tests, its dates and whether it is running.
get_experiment: One A/B test: its cells and how each cell did over the test window — spend, results and cost per result.
get_business_profile: The business behind this ad account as its owner described it: what it sells, its goal, target cost per result or ROAS, markets and rules.
infer_business_profile: Suggest a business profile from this ad account and its website: main goal, markets, what it sells. Saves nothing.
client_report_file: Make a report file for a client: this ad account's results for a period, with the agency's name, logo and commentary.
why_did_this_fail: What failed lately and why: your recent failed calls and approved changes that failed, with Meta's real error and who fixes it.
explain_error: Explain an error message from Meta or from this server: the cause in plain words, what to do and who does it.
list_catalogs: Product catalogs the business behind this ad account can use.
list_product_sets: Product sets of one catalog: the saved rules ads can promote.
list_products: Products of a catalog or of one product set, one page at a time, optionally only those matching a rule.
check_catalog_readiness: Whether a catalog is ready for dynamic ads: products, event sources, matching and must-fix diagnostics.
analyze_catalog_performance: Break catalog spend down by product: what sells, what is below target, what spends without a purchase.
product_performance: One product across the catalog ad sets: spend, purchases, return and its funnel.
catalog_funnel: View, add to cart, checkout and purchase across the catalog ad sets, with the biggest drop.
catalog_waste: Catalog spend that is bringing nothing back, by product, with how much of it is recoverable.
compare_product_sets: Product sets side by side by return, and the products that spend inside more than one of them.
list_catalog_data_sources: Where the products of a catalog come from: its feeds with their schedules and last uploads, and other data sources.
list_product_sets_for_product: Which product sets of its catalog a product is in.
product_feed_details: One product feed in full: file, schedule, format, default currency and its last upload.
list_feed_uploads: Recent fetches of a product feed: when, how many products were found and kept, errors and warnings.
list_feed_rules: Rules a product feed applies to its file: renamed columns, mapped values, letter case, defaults.
list_event_source_catalogs: Which product catalogs of the business a pixel is connected to as an event source.
list_instagram_posts: Recent posts, reels and stories of an Instagram account linked to this ad account, with whether each can become an ad.
list_lead_forms: Instant forms of a Facebook Page: name, status, how many submissions each has and the keys of its questions. get_insights, audit_conversion_tracking, audit_account, revenue_report are their own tools, not behind this router. Read-only and free: changes nothing and does not count toward the monthly change limit. An identical read within 30 seconds may return the same data (see data_age_seconds).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | list_tools: every operation with its field names, flags and router. execute: run the read named by tool_name. | |
| arguments | No | For execute: the fields of the operation, plus "connection" when several ad accounts are connected. Omit or {} when it has none. | |
| tool_name | No | For execute: the operation name from list_tools, e.g. list_campaigns. |