What it does
Ads Manager answers any question you can phrase as columns and a date range, which is the problem on a Monday: you have to remember the columns, set the comparison and scroll campaign by campaign. Most weeks the real question is short. Did Meta pay back last week, and which campaign changed?
This skill pulls the week from the Marketing API or Meta's ads MCP server, works out ROAS for the account and each campaign, and posts the number with eight weeks behind it. It reads reports only; nothing in your ad account changes.
How it works
1Pull last week by campaign
GET /act_<id>/insights?level=campaign&date_preset=last_week_mon_sun&fields=campaign_name,spend,purchase_roas,actions,action_values,impressions,cpm. Through the ads MCP server, use its reporting tools with the same dates; through the Meta ads CLI (released April 2026),meta ads insights get --date-preset last_week_mon_sun --fields spend,purchase_roas,actions,action_valuesat campaign level.2Pull the trend
For the account line and history, request
level=accountwithtime_rangecovering the last 8 full weeks andtime_increment=7, starting on a Monday so every bucket is a Monday-to-Sunday week.- 3
3Work out ROAS
ROAS is purchase value (the
purchaseentry inaction_values) divided byspend;purchase_roasgives the same per row. Purchases come fromactions. Flag campaigns under 1.0x with over $500 spend, and any campaign whose spend rose while ROAS fell by 20% or more. - 4
4Post the tile
ROAS is the headline as a multiple with 8 weeks of history. Spend, purchases and purchase value go in the glance; the campaign table and the flagged lines open with the card.
Post it to the board
With
BRIEFKIN_TOKENset, the agent sends the result as one card that updates in place every run. Without it, you get the report in the chat.
Install and run it
Pick your agent, where the data comes from and how to schedule it; the commands below follow.
Install the skill
One command. It puts the SKILL.md in ~/.claude/skills and in ~/.agents/skills, which Codex, Cursor, Gemini CLI, Copilot CLI and OpenCode read too.
shell
curl -fsSL https://briefkin.dev/skills/meta-ads-weekly-spend-and-roas/install | shRun it
Ask Claude Code:
prompt
Run the meta-ads-weekly-spend-and-roas skillOr paste the prompt instead of installing:
prompt
Using the Meta Marketing API insights endpoint (or Meta's ads MCP server, reporting tools only), get last week (Monday to Sunday) and the week before for my ad account, at account and campaign level: spend, purchases from actions, purchase value from action_values, and purchase_roas. Give me account ROAS as a multiple with the change, spend, purchases and purchase value with their changes, and a campaign table. Flag campaigns under 1.0x ROAS with over $500 spend, and campaigns whose spend rose while ROAS fell 20% or more. Do not change anything in the ad account.Put it on a schedule
Mondays at 8:00, from cron on any machine where Claude Code is signed in:
crontab
0 8 * * 1 claude -p "Run the meta-ads-weekly-spend-and-roas skill"Add it with
crontab -e. A laptop asleep at that time runs it when it wakes if you use launchd or Task Scheduler instead; GitHub Actions works for the API route.Send it to your board
Connect Briefkin once with
curl -fsSL https://briefkin.dev/install | shand every run lands on your board as a stat tile. How setup works
View the SKILL.mdRaw file
SKILL.md---
name: meta-ads-weekly-spend-and-roas
description: "Every Monday: last week's Meta Ads ROAS, spend and purchases, the change on the week before, and the campaign that drove it. Use when the user asks for this, or when it runs on a schedule."
---
# Meta Ads weekly spend and ROAS
Every Monday: last week's Meta Ads ROAS, spend and purchases, the change on the week before, and the campaign that drove it.
Ads Manager answers any question you can phrase as columns and a date range, which is the problem on a Monday: you have to remember the columns, set the comparison and scroll campaign by campaign. Most weeks the real question is short. Did Meta pay back last week, and which campaign changed?
This skill pulls the week from the Marketing API or Meta's ads MCP server, works out ROAS for the account and each campaign, and posts the number with eight weeks behind it. It reads reports only; nothing in your ad account changes.
## Two ways to get the data
Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.
## Route A: API or MCP server
### What you need
- Read access to the Meta ad account (an Advertiser or Analyst role) and its `act_` ID.
- Meta's ads MCP server (`https://mcp.facebook.com/ads`), the Meta ads CLI, or a Marketing API user token with `ads_read`. The MCP server also has tools that create and edit ads; the skill calls reporting tools only.
If something is missing, say what and stop; do not invent numbers.
### Steps
1. **Pull last week by campaign** (Meta Ads): `GET /act_<id>/insights?level=campaign&date_preset=last_week_mon_sun&fields=campaign_name,spend,purchase_roas,actions,action_values,impressions,cpm`. Through the ads MCP server, use its reporting tools with the same dates; through the Meta ads CLI (released April 2026), `meta ads insights get --date-preset last_week_mon_sun --fields spend,purchase_roas,actions,action_values` at campaign level.
2. **Pull the trend** (Meta Ads): For the account line and history, request `level=account` with `time_range` covering the last 8 full weeks and `time_increment=7`, starting on a Monday so every bucket is a Monday-to-Sunday week.
3. **Work out ROAS**: ROAS is purchase value (the `purchase` entry in `action_values`) divided by `spend`; `purchase_roas` gives the same per row. Purchases come from `actions`. Flag campaigns under 1.0x with over $500 spend, and any campaign whose spend rose while ROAS fell by 20% or more.
4. **Post the tile**: ROAS is the headline as a multiple with 8 weeks of history. Spend, purchases and purchase value go in the glance; the campaign table and the flagged lines open with the card.
## Route B: the browser
### What you need
- Signed in to Facebook with at least the Analyst (view-only) role on the ad account, or a Business portfolio user with view access to it.
If something is missing, say what and stop; do not invent numbers.
### Steps
Start at https://adsmanager.facebook.com/adsmanager/manage/campaigns. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.
1. **Set last week with a comparison**: Open Ads Manager, pick the ad account from the account menu at the top left, stay on the **Campaigns** tab and open the date picker. Choose **Last week** (Monday to Sunday), switch on **Compare** so the previous week shows next to it, and click **Update**.
2. **Add the purchase columns**: Under **Columns**, choose **Customize columns** and tick `Amount spent`, `Purchases`, `Purchases conversion value`, `Purchase ROAS`, `Impressions` and `CPM (cost per 1,000 impressions)`. Apply, and read the **Results from N campaigns** total row and each campaign row with its comparison value.
3. **Read the 8-week trend**: Change the date range to a custom range covering the last 8 full weeks starting on a Monday, set **Breakdown > By time > Week**, and read the account total row per week. Switch the breakdown off afterwards.
4. **Flag and write**: Account ROAS is the headline, with the 8 weekly values behind it. Flag campaigns under 1.0x ROAS with over $500 spent, and any campaign whose spend rose while ROAS fell 20% or more against the week before.
Note: Ads Manager's Compare view already shows both weeks, which makes this route easy to read for accounts with under 50 campaigns; past that, use **Reports > Export table data** and read the file. The web app only loads fully on desktop, and a column preset saved once ("Weekly ROAS") skips the customize step on later runs.
## The report
- **ROAS** last week as a multiple, with an 8-week trend.
- **Spend, purchases and purchase value**, each with the change on the week before.
- **By campaign**: spend, value and ROAS.
- **Flags**: campaigns losing money, and campaigns spending more for less.
## Post it to Briefkin
When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.
```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
-H "authorization: Bearer $BRIEFKIN_TOKEN" \
-H "content-type: application/json" \
-d @- <<'JSON'
{
"v": 1,
"event_id": "meta-ads-weekly-spend-and-roas/<date of this run, e.g. 2026-10-16>",
"item_key": "meta-ads-weekly-spend-and-roas",
"project": "Acme Store",
"source": "Meta Ads weekly spend and ROAS skill",
"kind": "metric",
"title": "ROAS 3.1x last week, down from 3.4x",
"metric": {
"label": "ROAS",
"value": 3.1,
"unit": "x",
"better": "higher",
"period_start": "<start of the period, ISO 8601>",
"period_end": "<end of the period, ISO 8601>"
},
"glance": {
"type": "Grid",
"props": {
"columns": 3
},
"children": [
{
"type": "Stat",
"props": {
"label": "Spend",
"value": 12480,
"prefix": "$",
"delta": 6,
"better": "lower"
}
},
{
"type": "Stat",
"props": {
"label": "Purchases",
"value": 412,
"delta": -3
}
},
{
"type": "Stat",
"props": {
"label": "Purchase value",
"value": 38690,
"prefix": "$",
"delta": -3
}
}
]
},
"widget": [
{
"type": "Table",
"props": {
"columns": [
"Campaign",
"Spend",
"Purchase value",
"ROAS"
],
"align": [
"left",
"right",
"right",
"right"
],
"rows": [
[
"Prospecting - Broad",
"$5,620",
"$13,490",
"2.4x"
],
[
"Retargeting - 30 days",
"$2,180",
"$11,120",
"5.1x"
],
[
"Advantage+ Shopping",
"$4,680",
"$14,080",
"3.0x"
],
[
"Total",
"$12,480",
"$38,690",
"3.1x"
]
]
}
},
{
"type": "Callout",
"props": {
"text": "Prospecting spend rose 18% while its ROAS fell from 3.0x to 2.4x. It explains most of the drop.",
"tone": "warn"
}
}
],
"size": "md"
}
JSON
```
Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.
Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters).
## Run it on a schedule
Suggested: Mondays at 8:00 (`0 8 * * 1`). From cron, with the agent signed in on that machine:
```bash
0 8 * * 1 claude -p "Run the meta-ads-weekly-spend-and-roas skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```
Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/meta-ads-weekly-spend-and-roas#schedule
Source: https://briefkin.dev/skills/meta-ads-weekly-spend-and-roas
What your agent needs
Read access to the Meta ad account (an Advertiser or Analyst role) and its
act_ID.Meta's ads MCP server (
https://mcp.facebook.com/ads), the Meta ads CLI, or a Marketing API user token withads_read. The MCP server also has tools that create and edit ads; the skill calls reporting tools only.
Connecting Meta Ads
- Meta Ads MCP server, Meta's official remote server at
https://mcp.facebook.com/ads, with tools for reporting, ad and catalog management, datasets and troubleshooting. You sign in through Facebook Login for Business. For Claude Code, Meta documentsclaude mcp add --transport http --client-id <META_APP_ID> meta-ads https://mcp.facebook.com/ads, using a Meta developer app with the ads MCP use case added; clients that send headers can pass a user access token as a Bearer token instead (get started). Codex and Cursor take the same URL. - Meta Ads CLI. Meta's command-line tool installs with
pip install meta-ads, reads the token fromACCESS_TOKEN, and returns insights withmeta ads insights get --fields spend,impressions,ctr,cpc, which suits scheduled runs from Claude Code or Codex. - Marketing API with a system user token. In Business Settings, create a system user, give it the ad account with View performance access, and generate a token with the
ads_readpermission. The skill readsMETA_ACCESS_TOKENandMETA_AD_ACCOUNT_ID(act_1234567890).
The MCP server can create and edit ads when you grant management permissions. For unattended reports, a system user with only ads_read and View performance can't touch a bid, a budget or an ad.
Questions
Why is Meta's ROAS higher than what my store reports?
Meta credits purchases within its own attribution window, including some people who saw an ad and bought later without clicking. Your store or GA4 counts each order once, usually by last click. Both are fine for spotting trends; for a total across channels, use store revenue over total ad spend.
Can the agent change my ads through the MCP server?
The ads MCP server has tools that create and edit campaigns, so the skill is written to call reporting tools only. For unattended runs, a token with just ads_read is the safer setup: it can read every report and change nothing.
Do I need Briefkin to use the Meta Ads weekly spend and ROAS skill?
No. The skill runs with your own agent and gives you the report in the chat. With a Briefkin token set, each run also posts it to your board as a stat tile, so you can glance at it instead of asking again.
Which agents can run it?
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, Windsurf and Amp all read SKILL.md files. The install command puts it in ~/.claude/skills and ~/.agents/skills, where they look. ChatGPT, the Claude app and Grok take the prompt instead. Pick your agent under "Install and run it" and the commands change to match.
Can it work without an API or MCP server, from my browser?
Yes. Switch the data source to "Your browser" and the steps change to the Meta Ads pages themselves: the agent opens adsmanager.facebook.com/adsmanager/manage/campaigns in a browser you are signed in to and reads the numbers off the page. Claude Code, Codex, Cursor, Claude app and ChatGPT can drive a browser out of the box; Gemini CLI, Copilot CLI and OpenCode need a Playwright or Chrome DevTools MCP server first. It is slower than the API and needs you signed in, so it suits a report you run by hand or from a scheduler on your own computer.