# Meta Ads through toolfare > Spend, CPA and ROAS by campaign, ad set or ad, live delivery with Meta’s own breakdowns, change history and Pixel health — answered inside ChatGPT, Claude, Codex or Cursor. Connect your ad account to toolfare once; your AI reads it with your own login, and every read is free. Page: https://toolfare.ai/meta-ads ## Use it from your agent Paste this into Claude Code, Codex, Cursor or any agent with a shell: > Set up https://toolfare.ai/skill.md, then use toolfare to answer: What was our Meta CPA by campaign last week? Apps without a terminal connect toolfare as an MCP server: https://toolfare.ai/docs#connect ## Use it from a script ```sh mkdir -p ~/.local/bin curl -fsSL 'https://toolfare.ai/toolfare/toolfare.mjs' -o ~/.local/bin/toolfare chmod +x ~/.local/bin/toolfare export PATH="$HOME/.local/bin:$PATH" export TOOLFARE_MCP_URL='https://api.toolfare.ai/mcp' toolfare login ``` Then connect your Meta Ads account in the toolfare console (https://toolfare.ai/meta-ads#setup); calls fail until it is connected. Sign in once per machine; the CLI renews the sign-in itself. On a CI runner or another server, create an API key in the toolfare console and set it as `TOOLFARE_API_KEY` instead of signing in. Paid calls on one sign-in or key run one at a time. `--max-cost` refuses a call quoted above that many credits (1,000 credits = $3). ## Tools ### CPA and ROAS by campaign, ad set, ad or day Tool: `ads_query_single_dimension` Spend, clicks, conversions, CPA and ROAS, grouped by one dimension over a date range — read from toolfare’s synced copy of the account, so a whole month answers in one call. Ask: - What was our Meta CPA by campaign last week? - Which ads had the best ROAS over the last 30 days? ### Live delivery, with Meta’s own breakdowns Tool: `ads_get_insights` Up-to-the-minute Insights at account, campaign, ad set or ad level, broken down the way Ads Manager does — age, gender, country, placement. Ask: - How is this campaign delivering right now? - Break down yesterday’s spend by age and placement. ### Every campaign, as it stands on Meta Tool: `ads_list_campaigns` The live campaign inventory with status, objective and budget — what is actually running, not what a report last saw. Ask: - Which Meta campaigns are active, and what are their budgets? - List the campaigns that are paused. ### Who changed what, and when Tool: `ads_get_change_history` The ad account’s own activity log: who made each change, to which object, and what it was — the first thing to read when a result moves overnight. Ask: - Who changed the budget on this campaign this week? - What changed in the account before performance dropped? ### Whether your Pixel signal is healthy Tool: `ads_get_dataset_quality` Event stats and match rate for a Pixel or Conversions API dataset, so a CPA spike can be ruled in or out as a tracking problem before anyone touches the ads. Ask: - Is our Meta Pixel signal quality healthy? - What match rate is our dataset getting? ### What Meta itself recommends Tool: `ads_get_opportunity_score` The account’s opportunity score and the recommendations Meta attaches to it, read straight from the Graph API. Ask: - What does Meta recommend we fix in this account? - What is our account’s opportunity score? ### Also available - `ads_audit_ad_automation_inventory`: Audit every tracked automation setting against the live account - `ads_audit_creative_automation`: Check whether AI-automation settings drifted from what was approved - `ads_create_ad`: Draft a paused ad from a creative - `ads_create_ad_creative`: Draft an ad creative - `ads_deploy_image_ads_batch`: Draft paused image ads in an ad set - `ads_deploy_video_ads_batch`: Upload videos and draft paused ads in an ad set - `ads_estimate_audience_size`: Estimate the reach of a targeting setup - `ads_generate_ad_preview`: Preview how an ad renders - `ads_get_account_info`: Account status, currency, spend and billing facts - `ads_get_account_pages`: The Pages and identities the account can advertise as - `ads_get_ad`: One ad’s live status, creative and tracking - `ads_get_ad_creative`: One creative’s content - `ads_get_ad_creatives`: The creatives attached to one ad - `ads_get_adset`: One ad set’s targeting, budget and bidding - `ads_get_campaign`: One campaign’s live settings and status - `ads_get_catalog_diagnostics`: Feed and item problems in a product catalog - `ads_get_connected_instagram_accounts`: The Instagram accounts connected to the ad account - `ads_get_custom_conversion`: One custom conversion - `ads_get_data_readiness`: Which date ranges have finished syncing - `ads_get_deploy_readiness`: Whether conversion tracking is ready for a conversion campaign - `ads_get_lead_form`: One lead form, its Page, questions and thank-you page - `ads_get_leads`: The leads a form or an ad collected - `ads_get_offline_conversion_readiness`: Whether offline conversions are set up to be received - `ads_get_page_whatsapp_destination`: Whether a Page has a WhatsApp number linked for lead ads - `ads_get_product_catalog_details`: One product catalog - `ads_get_product_feed_details`: One product feed - `ads_get_product_feed_rules`: The rules on a product feed - `ads_get_video`: Whether an uploaded Meta video is ready to use in an ad - `ads_list_ad_accounts`: The ad accounts your toolfare account can read - `ads_list_ad_creatives`: Every creative in the account - `ads_list_ad_labels`: Ad labels - `ads_list_ad_rules`: Automated rules and what they do - `ads_list_ads`: The ads in an account, campaign or ad group - `ads_list_adsets`: Ad sets, with budget and targeting - `ads_list_conversion_actions`: The conversion actions the account tracks - `ads_list_custom_audiences`: Custom audiences - `ads_list_custom_conversions`: Custom conversions - `ads_list_instagram_media`: Posts published by a connected Instagram account - `ads_list_lead_forms`: Lead forms and their questions - `ads_list_pixels`: Pixels, and when each one last fired - `ads_list_product_catalogs`: Product catalogs - `ads_list_product_set_products`: The products in a product set - `ads_list_product_sets`: The product sets in a catalog - `ads_list_products`: The products in a catalog - `ads_list_saved_audiences`: Saved audiences - `ads_preview_automation_baseline`: Read an entity’s current automation settings - `ads_query_multi_dimension`: Performance broken down by several dimensions at once - `ads_search_geo_locations`: Look up location targeting keys - `ads_search_interests`: Search interest targeting - `ads_search_targeting`: Look up job, behavior, industry and income targeting - `ads_upload_images`: Upload images to the ad account library - `ads_upload_video`: Upload a video to the ad account library ## Price Free to read: it is your own account, so toolfare pays nobody for the data and charges nothing per read. No per-read charge to observe. Reads need no purchase. Like every toolfare call, they run only while your balance holds at least $0.003, and that is not spent. Balances and top-ups are in US dollars. Quotes and `--max-cost` count credits: 1,000 credits = $3 ($0.003 each). ## Use it when - Your Meta CPA or ROAS moved and you want the campaign, ad set or ad that moved it. - You want delivery right now, or broken down by age, gender, country or placement. - Something changed overnight and you need to know who changed it. - You suspect tracking rather than creative, and want Pixel signal quality before touching the ads. ## Look elsewhere when - You want what your competitors are running. Your ad account only knows your own ads — ask an ad library instead. - You want what happened after the click. That is your analytics account. - You want to change a budget or pause an ad. Over MCP your AI can only propose new ads, and each one waits for your approval in toolfare. ## Limits - The reporting tool reads toolfare’s synced copy of the account. A freshly connected account backfills in stages, so an older date range can still be syncing — which is not the same as zero spend. - Live reads go through Meta’s own API and are subject to its rate limits. - Only accounts you connected are readable; nothing outside that grant is.