Connecting an ad account brings its campaigns, spend and platform-reported conversions into granvl, next to the leads granvl tracked on your own pages. Use it to see what each campaign really costs per lead, and to let your agent build campaigns within limits only a person can change.
Before you begin
You need access to the Meta Business or Google Ads account you want to connect. To let your agent build Meta campaigns, the Meta connection needs Manage access.
Any workspace member can connect an account. Sync now, Conversions counted and the limits under Settings > Ad Guardrails are for workspace owners and admins.
Connect Meta Ads or Google Ads
Open Meta Ads or Google Ads in the sidebar. You can also start from Settings > Meta Ads or Settings > Google Ads with + Connect Meta account or + Connect Google account.
Click Connect Meta account or Connect Google Ads.
Sign in with Meta or Google and approve the access it asks for.
Back in granvl, tick the ad accounts to bring in under Choose the ad accounts to bring in, then click Use these accounts.
Unticked accounts stay hidden and are not synced. granvl starts the first sync, and numbers fill in over the next few minutes.
Assign accounts to brands
Each ad account belongs to a brand, and the Meta Ads and Google Ads pages show only the accounts assigned to the brand you have selected. Manage this under Settings > Meta Ads or Settings > Google Ads:
Connections lists each login with its health: Healthy, Sync error, Token expired or Token expires in a number of days. Use Reconnect when a token has expired.
Ad account lists the accounts in use. Pick a brand under Assigned brands, or click Hide to stop syncing an account. Unassigned accounts belong to your default brand.
Hidden accounts lists accounts you hid. Click Restore to bring one back.
If a brand has no account assigned, its Meta Ads or Google Ads page offers a button to assign one.
How syncing works
When you connect an account, granvl imports up to the last 90 days of history. It never pulls further back than that.
After that, each account refreshes automatically about twice a day, re-reading the last few days so late conversions land. Once a week granvl re-reads the last 28 days to pick up the platforms' own corrections.
Sync now starts a refresh by hand. It is available once every 12 hours; the button shows when the next one is allowed.
The header shows when the account last synced. On Google Ads, a failed or paused sync shows a banner, and the numbers stay at the last successful run until it recovers.
If numbers look missing or stale, ask your agent to run get_ad_data_status. It reports the last successful sync, staleness and any sync error without calling the ad platform.
Read the Meta Ads and Google Ads pages
Both pages show one ad account at a time. Pick it from the account menu; granvl remembers your choice next time.
Date range: Last 7 days, Last 30 days or Last 90 days. Only campaigns, ad sets and ads that spent in the range appear, plus live campaigns that have not spent yet.
Chart: the daily trace for the metric you pick: Conversions, CPA, CTR, CPC, CPM or Spend.
Levels: Campaigns, Ad sets and Ads on Meta Ads; Campaigns, Ad groups, Ads, Keywords and Search terms on Google Ads. Tick rows at one level to narrow the next level to them.
Status filter and Columns sit above the table. Your column choice is remembered in this browser.
Delivery switch: the switch beside each row pauses or starts that campaign, ad set or ad on the platform right away.
Insights opens the account's Ads Insights page.
On Google Ads, click a campaign's budget to open Edit campaign budget. The new daily budget goes to Google when you save, and your workspace limits still apply.
What the columns mean
There are three ways to count a lead, and the table shows them side by side:
Platform-reported: what Meta or Google says the ads produced, by their own attribution.
granvl-tracked: form submits and conversion clicks granvl recorded on your pages from that ad's traffic. Bot traffic is excluded.
Qualified: granvl-tracked leads your qualification rule or CRM marked as qualified. See Qualify leads.
Column | What it shows |
Budget | Daily budget, or a lifetime budget marked "total". On Meta, a campaign that keeps its budget on its ad sets shows the sum of its live ad-set budgets |
Spend | What the platform reports spending in the range |
Link clicks / Clicks, Link CPC / CPC, CPM, CTR | Delivery numbers from the platform |
Landing page views | Meta's landing page views (Meta Ads only) |
Meta conv / Google conv | Platform-reported conversions |
Meta CPL / Google CPL | Spend divided by platform-reported conversions |
Granvl conv | granvl-tracked leads from this row's traffic |
Granvl qualified | Qualified leads from this row's traffic |
Granvl CPL | Spend divided by granvl-tracked leads |
Conv % | granvl-tracked leads divided by the visitors this row sent |
On Meta Ads, the Ads level also tags each ad that spent with a quick verdict against the account's median cost per lead. Hover it to see why.
To see why the platform's count and granvl's count differ, read Understand first-party analytics and attribution.
Choose which Meta conversions count
Standard Meta conversions (leads, purchases, schedules, registrations, contacts) always count in Meta conv. If you track leads with a custom conversion, add it:
On Meta Ads, pick the account and click Conversions counted.
Tick the custom conversions to include. All pixel custom events (unnamed) counts every custom event the pixel fires.
Click Save.
Saving re-reads the last 90 days of Meta data so history is counted the same way. Counts update as the sync lands.
Tag your ads with UTMs
UTMs are how granvl joins a click to the campaign, ad set and ad that sent it. Put them in each platform's own URL-parameter field, not in the landing page URL:
Meta: the ad's URL parameters field.
Google Ads: the Final URL suffix.
To get the parameters, open the funnel, click its published URL under the funnel name, and choose Meta UTMs only or Google UTMs only. Meta URL + UTMs and Google URL + UTMs copy the full link instead. The parameters use each platform's own macros, so every click reports its campaign, ad set and ad IDs.
Ads your agent builds through granvl are tagged automatically: give it the plain landing page URL.
Build campaigns through your agent
Ask your agent to plan and build campaigns. It works through the granvl tools step by step (for example create_meta_campaign, create_meta_adset and create_meta_ad on Meta, or create_google_search_campaign on Google), and campaign_preflight checks the launch first: account connected, budget under your limits, landing page live with a form and tracking.
Plan a Meta lead campaign for my mortgage quiz funnel at $40 a day.
Run the preflight check and show me the plan before you build anything.
On a granvl domain, the landing page must be published before an ad can point at it.
Everything your agent creates starts paused. Your agent cannot switch anything on; you do that in the platform's ads manager or with the row's delivery switch in granvl.
Meta ads run under an ad identity: the Facebook Page and Instagram account for that ad account. Ask your agent to set it with
set_ad_identitybefore the first Meta ad.Budgets your agent sets are checked against the limits below. An over-limit request fails with the limit in the error.
Ad Guardrails
Settings > Ad Guardrails holds hard limits on what agents can spend through granvl. Only workspace owners and admins can change them. No agent tool can change them, so an agent can never raise its own limit.
Limit | What it caps |
Platform ceiling | $200 a day on any single campaign or ad-set budget set through granvl. It is a product limit, not a setting |
Maximum daily budget | Your workspace's cap on any single budget set through granvl, across all ad platforms. It can only lower the platform ceiling |
Per-account limits | An optional daily spend cap per ad account. A new budget is refused if the account's live daily spend (its highest day in the last 7 days) plus the new budget would go over it |
These limits apply to changes made through granvl. For a limit that applies to every tool, also set an account spending limit in Meta Ads Manager or a monthly account budget in Google Ads.
Budget changes need a person
When your agent wants to change a Google Ads campaign's budget, it can only propose it. The proposal appears on Google Ads under Budget changes awaiting your approval, with the reason. Click Apply budget to send it to Google, or Dismiss. Nothing changes on Google until you apply it.
Diagnose performance with your agent
Ask your agent questions like "which ad sets got leads cheapest last week?" It reads these tools:
get_spend_summary: spend joined to granvl-tracked and qualified leads, with cost per lead and cost per qualified lead.get_ad_to_lander_performance: which landing page variants each ad's traffic reached, and how they converted.get_ad_breakdownsandcompare_ad_sets: results by segment, and ad sets side by side.get_tracking_health: campaigns whose clicks can't be joined, usually missing or broken UTMs.get_ad_healthandget_ad_data_status: delivery problems and sync freshness.
Disconnect an account
In Settings > Meta Ads or Settings > Google Ads, click Disconnect on the connection. Data already synced stays until it is deleted. To stop syncing one account but keep the connection, use Hide instead.