Meta ads

Connect a Meta (Facebook and Instagram) ad account to your project and Voidhash keeps a read-only copy of its campaigns and daily spend. It joins that spend with the people each campaign, ad set and ad brought in, and with what those people went on to do, so one report shows cost per trial, cost per payer and the return on ad spend measured on real revenue.

Voidhash only reads from Meta. It never changes a campaign, budget or ad.

Before you start

Voidhash attributes people to an ad from the ad's landing page URL. Add the campaign, ad set and ad IDs to every ad's URL parameters and install the web SDK on the landing page, as described in Page views and attribution. Without the IDs, spend still syncs, but no people are matched to it.

You also need:

• Admin access to the business in Meta Business Manager that owns the ad account.
• An app owned by that business. Any app type works; it is only used to issue the token.
• A Voidhash user or secret key with the project:ads:manage permission to connect the account.

Create a system user token

A system user is a non-human user of your business. Its token keeps working when people leave your team and does not need Meta's app review.

Treat the token like a password. Voidhash stores it encrypted and never shows it again, in the dashboard or through the API.

Connect the account

In the dashboard, open Ads → Connections and select Connect next to Meta. Enter the token and choose the ad accounts to read. Voidhash checks that the token grants ads_read and can read the account, then records the account's name, currency and time zone. If the check fails, the message says what to fix.

Through the API, send the same values to POST /api/v1/ad-accounts:

curl https://api.voidhash.com/api/v1/ad-accounts \
  -H "x-secret-key: $VOIDHASH_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "network": "meta",
    "accountId": "act_1234567890",
    "accessToken": "EAAB...",
    "backfillDays": 90
  }'

Connecting an account that is already connected replaces its token. Use this when you rotate the token or after a sync stopped. A project can connect several ad accounts.

What is synced, and how often

The first sync starts as soon as the account is connected. After it, Voidhash syncs every account about every six hours.

• Account health: the account's status in Meta (active, disabled, unpaid balance, grace period, under review or closed) with Meta's reason, its spending limit and how much of it is spent, and the business portfolio that owns it.
• Campaigns, ad sets and ads: IDs, names, status, budget, bid strategy, objective, the event each ad set optimizes for, start and end, where each ad sends people, and when each was created and last updated. Archived and deleted objects are included; an object Meta stops listing is marked removed and keeps its last known name.
• Creatives: format (image, video or carousel), thumbnail, video length, primary text, headline, call to action, landing URL and URL parameters, and which ads use each one.
• Daily delivery per ad: spend, impressions, clicks, link clicks, results, video plays of at least three seconds and ThruPlays, and Meta's reported purchases with their value, app installs, leads, landing page views, registrations, subscriptions and trial starts, for ads in every status, including paused, archived and deleted ones. Each day is dated in the ad account's time zone, and amounts are in its currency. Conversions are counted with the ad account's attribution setting, the same numbers Ads Manager shows, and the setting is stored with each day. Meta reports one conversion under several overlapping action types, so each kind counts the first type present, starting with the cross-channel total (such as omni_purchase), instead of adding them up.
• Breakdowns: the same daily delivery split by platform (Facebook, Instagram, Audience Network, Messenger), placement, country, device, and age and gender, for the last 28 days.
• Daily account totals: the whole account's spend, impressions and clicks per day. They include spend Meta no longer reports ad by ad, such as on some deleted ads, so totals stay complete.

Reach and frequency count people, so they don't add up across ads or days. Voidhash reads them from Meta for exactly the campaigns, ad sets, ads and days you look at, and never adds them together; a total that would need adding them shows no reach.

The first sync pulls the last 90 days, or the number of days you set with backfillDays, up to three years. Meta keeps adjusting delivery and attributed conversions for up to 28 days, so every later sync pulls the last 28 days again and replaces what it stored for the ads Meta reports. Days stored for an ad Meta no longer reports are kept. Connecting the account again with a larger backfillDays pulls the longer history on the next sync.

Each account in Ads → Connections shows when it last synced, the last error, and when the next sync runs.

• A sync that fails because Meta is unavailable or rate-limits the request is retried an hour later, or later still when Meta asks for a longer pause. The status shows Sync error until a sync succeeds.
• When the token is revoked or expires, or loses access to the ad account, syncing stops and the error says why. Generate a new token, select Reconnect and enter it to resume; the connected accounts are selected, and their token is replaced.

Statuses

Each campaign, ad set and ad has two statuses and the reasons behind them:

• Configured is what you set in Ads Manager: on, paused, or removed (archived or deleted).
• Delivery says whether it runs: delivering, learning (with its progress, such as 31 of the 50 optimization events Meta needs in seven days), learning limited, in review, rejected, paused, off because a parent campaign or ad set is off, scheduled, ended, not delivering, or stopped by an account issue such as missing payment information.

Reasons explain anything less than delivering: the policy Meta rejected an ad under, with Meta's explanation; issues Meta reports on the object; learning that can't finish; or, for a campaign or ad set, children that don't deliver or are rejected. An ad set whose ads all wait for review or their start date shows as in review or scheduled, not as not delivering. A campaign is shown as learning or learning limited when most of its delivering ad sets are. Voidhash only reports these states. Change them in Ads Manager; every object has a link that opens it there.

After every sync, Voidhash also lists the account's issues: rejected ads, learning-limited ad sets, objects that are on but not delivering, account problems, a spending limit that is 80% or more used, and a sync that failed.

Destinations

Each ad is marked by where it sends people:

• App store: app promotion campaigns, and ad sets that promote an app.
• Website: ads that link to a web page.
• Web-to-app: website ads that link to a page that hands people over to your app. List the start of those pages' addresses, such as example.app/start, as your project's web-to-app landing pages. An ad whose link is that page, or a page under it, is web-to-app. Changing the list applies to synced ads right away.

Ad sets and campaigns take their ads' destination when all of them share one, and are marked mixed when their ads go to different ones.

Voidhash also checks that every active website ad's link carries campaign_id (or utm_id), adset_id and ad_id, either in its URL or in its URL parameters, and reports the ads, and the share of spend, that miss them.

To disconnect an account, open its menu in Ads → Connections and select Disconnect. Disconnecting an account deletes everything synced from it. Connecting, reconnecting and disconnecting are recorded in the project's audit log, without the token.

Campaign performance

The Ads → Campaigns page, the campaign performance endpoint and the campaign_performance MCP tool report one row per campaign, ad set or ad for a range of days:

curl https://api.voidhash.com/api/v1/analytics/queries/campaign-performance \
  -H "x-secret-key: $VOIDHASH_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{ "from": "2026-09-01", "to": "2026-09-30", "level": "campaign" }'

Rows include campaigns with spend but nobody attributed, and campaign IDs people arrived from that no connected account has synced (isSynced is false). Account spend that no ad row accounts for, usually on deleted ads, is reported as unallocated and counted in totals, so the total spend matches the account. Reading the report requires project:ads:read and project:analytics:read.

A ratio is null when what it divides by is zero. People are attributed by their first touch, as in the acquisition report (see ad measurement for the definitions), so roas counts each person's revenue once, on the ad that first brought them in. metaRoas uses Meta's own attribution and can count the same purchase for several ads; the two often differ.

By default money is reported in the ad account's currency and days follow its time zone, so spend and outcomes line up with Ads Manager. You can ask for another currency; spend is then converted at each day's exchange rate. When you ask for another timezone, people and revenue follow it but spend stays dated in the account's time zone, and the report adds a warning. Accounts with different currencies or time zones need an explicit currency and timezone, or one adAccountId.

Revenue comes from production purchases unless you set environment. Recent days are incomplete: spend for today is still accruing, and people acquired recently have had less time to convert. Use revenueWindow to compare cohorts over the same number of days.