Meta Ads: accounts and reporting
Ad accounts, what is in them, and the reports. 10 tools. This page is generated from the server's own tool list, version 0.1.0, and is not edited by hand. The descriptions are the ones your AI client reads, so they are written for it. All tools lists every page.
meta_ads_list_accounts
Kind: read. It is marked as changing nothing.
List the Meta ad accounts your Meta login can advertise from. Call this first: every other meta_ads_* tool takes an ad_account_id from here.
Each account carries its currency (all money in meta_ads_* tools is in that currency's units), timezone, status, amount spent, the account's own spending limit and Meta's minimum daily budget, the Facebook Pages and Instagram accounts it can advertise for, and this installation's spending limits for its currency. An account marked allowed=false, or one whose spend_limits has a how_to_set note, cannot be changed from here until an administrator acts; the note says where.
It takes no arguments.
meta_ads_list
Kind: read. It is marked as changing nothing.
List the campaigns, ad sets or ads of a Meta ad account, with their status, objective, budgets and schedule. Budgets are in the account's currency units.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
level | text | no | "campaign" | "campaign", "adset" or "ad". |
parent_id | text | no | none | Only what is under this campaign (for ad sets and ads) or ad set (for ads). |
statuses | list of text | no | none | effective_status values to include, e.g. ["ACTIVE"]. Left out, everything except ARCHIVED and DELETED; name those to see them. |
limit | whole number | no | 50 | Rows per page (1-100). |
after | text | no | none | next_after from the previous page. |
meta_ads_performance
Kind: read. It is marked as changing nothing.
Report how a Meta ad account's campaigns, ad sets or ads performed: spend, impressions, reach, frequency, clicks, link clicks, CTR, CPC, CPM, actions by type with their cost, leads and cost per lead, conversations started and cost per conversation, and how far videos were watched. One row per object (and per breakdown value). Spend and costs are in the account's currency units.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
level | text | no | "campaign" | One row per "account", "campaign", "adset" or "ad". |
object_id | text | no | none | Report only on this campaign, ad set or ad. |
date_preset | text | no | none | e.g. today, yesterday, last_7d, last_30d (the default), this_month, last_month, maximum. Or give since and until instead. |
since | text | no | none | First day, YYYY-MM-DD, in the ad account's timezone. |
until | text | no | none | Last day, YYYY-MM-DD. |
breakdowns | list of text | no | none | Split each row by age, gender, country, region, publisher_platform, platform_position, impression_device or device_platform. Meta allows only some combinations, e.g. ["age", "gender"] or ["publisher_platform", "platform_position"]. |
fields | list of text | no | none | Metrics to return instead of the default set. Beyond the default: unique counts (unique_clicks, unique_actions, cost_per_unique_click, cost_per_unique_action_type), more video figures (video_play_actions, video_p95_watched_actions, video_30_sec_watched_actions, video_avg_time_watched_actions, video_thruplay_watched_actions, cost_per_thruplay), action_values, and at ad level quality_ranking, engagement_rate_ranking and conversion_rate_ranking. |
include_paused | true or false | no | true | False to report only on what is ACTIVE now. |
limit | whole number | no | 50 | Rows per page (1-100). |
after | text | no | none | next_after from the previous page. |
time_increment | whole number or text | no | none | Cut the period into rows of this many days (1 for a daily series, up to 90) or "monthly"; each row then carries date_start and date_stop. |
attribution_windows | list of text | no | none | Report the actions under each of these windows side by side (actions_by_window): 1d_click, 7d_click, 28d_click, 1d_view, 1d_ev. Left out, the ad set's own setting, as Ads Manager shows it. |
meta_ads_get_delivery_status
Kind: read. It is marked as changing nothing.
Explain why a Meta campaign, ad set or ad is or is not delivering: its effective status in words, the issues Meta reports on it, an ad's review feedback (why it was rejected), an ad set's learning stage, and Meta's recommendations.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
level | text | yes | "campaign", "adset" or "ad" - what object_id is. | |
object_id | text | yes | From meta_ads_list. |
meta_ads_creative_report
Kind: read. It is marked as changing nothing.
Report on a Meta ad account ad by ad, with what each ad shows beside how it did: the creative's headline, text, button and thumbnail, the usual figures, leads and conversations with their cost, and Meta's three rankings of the ad against its competitors (quality, engagement rate, conversion rate). Two calls to Meta.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
object_id | text | no | none | Only the ads under this campaign or ad set. |
date_preset | text | no | none | e.g. last_7d, last_30d (the default), this_month, maximum. Or give since and until instead. |
since | text | no | none | First day, YYYY-MM-DD, in the ad account's timezone. |
until | text | no | none | Last day, YYYY-MM-DD. |
include_paused | true or false | no | true | False to report only on ads that are ACTIVE now. |
limit | whole number | no | 25 | Ads per page (1-100). |
after | text | no | none | next_after from the previous page. |
meta_ads_ad_fatigue
Kind: read. It is marked as changing nothing.
Day by day, how often each running Meta ad was seen and how often it was clicked, and which ads look worn out: seen more often and clicked less in the later half of the period than in the earlier. The flag is this server's rule of thumb and the answer states it; the daily figures are Meta's.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
object_id | text | no | none | Only the ads under this campaign or ad set. |
days | whole number | no | 14 | 7, 14 (default) or 28. |
meta_ads_budget_pacing
Kind: read. It is marked as changing nothing.
How the live budgets of a Meta ad account are being spent: for each daily budget, what was spent today; for each lifetime budget, what is spent and left, how much of its time has passed, and whether it is ahead of or behind an even spend. Two calls to Meta.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. |
meta_ads_learning_status
Kind: read. It is marked as changing nothing.
Which live ad sets of a Meta ad account are still learning, which have settled, and which are learning limited (too few results to settle), with what usually helps. One call to Meta.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. |
meta_ads_boosted_post_report
Kind: read. It is marked as changing nothing.
A post that was advertised, paid beside organic: what the ads that show it spent and delivered, and the post's own figures split into paid and organic where Meta splits them.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | The ad account the post was advertised from. | |
page_id | text | no | none | The Facebook Page the post is on, with post_id. |
post_id | text | no | none | The Page post, from meta_list_posts. |
instagram_user_id | text | no | none | Or the Instagram account, with instagram_media_id. |
instagram_media_id | text | no | none | The Instagram post, from meta_list_posts. |
meta_ads_change_history
Kind: read. It is marked as changing nothing.
The change history of a Meta ad account: who changed what and when, whether through this server, Ads Manager or anything else - a budget, a status, targeting, a new ad. Newest first. This server's own activity log (get_audit_log) holds only what was done through it.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | text | yes | From meta_ads_list_accounts. | |
since | text | no | none | First day, YYYY-MM-DD. Left out, Meta's own default (the last few days). |
until | text | no | none | Last day, YYYY-MM-DD. |
object_id | text | no | none | Only changes to this campaign, ad set or ad, among those on the page. |
limit | whole number | no | 50 | Rows per page (1-100). |
after | text | no | none | next_after from the previous page. |