Stream a Meta ad account

A Meta Ads stream lands an ad account's spend, reach, clicks and leads in your warehouse, day by day, with its campaigns, ad sets and ads, and the enquiries people send through your Facebook Page's instant forms. Each run reads the last few weeks of figures again, because Meta keeps adding leads and sales to the day of the ad that led to them.

Meta Ads is a published source, like Postgres and Bite: sanda wrote the code that reads it and runs it as its own, so there is no connector for sam to write or for anyone to approve. Someone in the business connects Meta, you choose the ad account, the Page and what to read, and you set a schedule.

Before you start

• Someone in the business connects Meta. Whoever connects signs in with Facebook, chooses the business portfolio, and picks the ad accounts and Facebook Pages to share with sanda. They need to see the ad account in Ads Manager and, for leads, have a role on the Page. In sanda, only owners and admins connect Meta and make a stream on it.
• A business portfolio. Meta connects a business rather than a person, so the ad accounts and Pages belong to a business portfolio. If the business has none yet, Meta asks to make one while connecting.
• One connection, several accounts. A Meta connection is whatever the business shared: several ad accounts and Pages at once. Each stream reads one ad account and, for leads, one Page, so a business with two ad accounts makes two streams on the same connection.
• Leads need lead access. A Page's admins choose who may read its leads, in Meta's Leads Access Manager. If the Page limits it, a Page admin gives the person or business that connected Meta access to leads.
• Meta lists more than sanda uses. Meta ties reading leads to permissions for managing a Page's ads, so its screen asks for those too. sanda only ever reads: every request it sends asks for figures, lists or leads, and nothing else is let through.

Connect Meta

sanda keeps the connection encrypted, and it is never shown, in the console or to sam. Connect again connects it again: choose the same business, ad accounts and Pages, and every stream on the connection carries on. If the new connection shares less than the streams on it read, the line at the top says so: connect again and choose everything they use. Disconnect forgets the connection in sanda. Meta keeps sanda listed in the business's connected apps until a business admin removes it there, in Meta's Business Settings, under Integrations · Connected apps.

A connection made as a person rather than as a business lasts about 60 days. From a week before it ends, its row under Connected and the Overview tab say when, and Connect again renews it.

Make a stream

What it reads

Something the connection didn't allow (leads, say) is marked not allowed by this Meta connection in the editor, and sanda won't save a stream that reads it. Connect Meta again and allow it, or leave it off.

Campaigns, ad sets and ads

Each run reads every campaign, ad set and ad in the ad account, with its name, status and dates: those running, paused and archived alike. Meta stops listing one once it is deleted, so its row stays with the name it had and is marked _deleted_at. Every performance row carries its campaign's, ad set's and ad's names as well, so last year's spend still has a name. A campaign also has its objective, an ad set its campaign and optimisation goal, and an ad its ad set and campaign.

Performance by day

The three performance tables hold the same figures at three levels: each campaign, each ad set and each ad, one row a day. A row has the day's spend, impressions, reach, clicks and link clicks, and every action Meta counted, with its value.

Each run reads the last 28 days again, one day at a time, oldest first. Meta adds a lead or a sale to the day of the ad that led to it, for weeks after, so a day's figures keep changing for a while, and reading them again is how they land. A first run walks from the history date to today, which for a long history takes several runs, each carrying on from the last.

A day is the ad account's own day, in its time zone, as Ads Manager shows it. Each day includes the campaigns, ad sets and ads archived or deleted since, so a day's rows add up to the ad account's figures in Ads Manager. A row that Meta no longer returns for a day inside the window is marked _deleted_at, so the rows that aren't marked add up to what Meta says now.

Leads and lead forms

Each run reads the leads that came in since the last run, form by form across the Page's instant forms, starting 24 hours before the newest lead the last run saw, so a lead Meta shows late still lands. A lead read twice is still one row. Lead forms lists the Page's forms by name, so each lead can be labelled with its form.

Meta keeps a lead for about 90 days after it is sent, so a stream that hasn't run for longer than that has missed the leads in between. Keep a leads stream running.

Left out

• Breakdowns and hourly figures: by age, gender, region or placement, and by the hour. Each multiplies the rows of every day, so they are not read yet.
• Ad creatives, budgets and bids: the images and words of an ad, and what a campaign or ad set may spend.
• A form's questions and status: Meta's reference doesn't say how to read them, so a lead form lands with its name alone. Each lead still carries its own questions and answers.
• Leads that arrive another way: through Messenger or your website. Meta counts them in a day's leads, but only instant form leads are read one by one.
• Page posts and Page insights, and the events a Conversions API push sends to Meta.

What lands in your warehouse

Every field becomes a column, and the whole record is kept in _record, as for every pull. A few things are worth knowing when you model them:

• Figures are numbers. Spend is in the ad account's currency, which each row names in account_currency. Impressions, reach and clicks are whole numbers.
• leads is the day's leads. sanda adds it to every performance row from Meta's own lead action, which already adds up every kind of lead: instant forms, Messenger and your website's pixel. Don't add the kinds in actions to it again.
• Actions are JSON lists. actions, action_values and cost_per_action_type each hold one entry for every kind of action, with its action_type and value.
• Days are the ad account's: date_start and date_stop are the same day, in the ad account's time zone. Times on campaigns, ad sets, ads and leads carry their offset, so they land as times with a zone.
• Ids are text, as Meta sends them. A performance row's campaign_id, adset_id and ad_id name rows of campaigns, ad sets and ads, and a lead's ad_id and form_id name rows of insights_ad_daily and lead forms. A lead that came through the form without an ad (an organic lead) has no ad_id.
• A lead's answers come twice: as Meta sends them, in field_data, and as one object of question and answer in answers, so a view can read answers->>'phone_number'. A question with several answers holds a list.
• Leads are personal details. A lead lands the name, phone and email someone typed, so treat the leads table as you would any customer list.

Change a stream

Edit, on the stream's page, changes everything but the ad account, the Page and the warehouse. A stream made without a Page can't read lead forms or leads: make a new stream for them. Something you take off keeps its table, with what it landed. A new Read history from date takes effect the next time everything is read from the start: press Load everything again on the stream's page.

When something goes wrong

A failed run counts toward the stream pausing itself, as any stream's does. See runs.

Limits

• A Meta Ads stream runs at most every 60 minutes, because Meta counts every read against the ad account's hourly allowance, which the business's other ad tools share.
• A run makes at most 2 requests a second, and each request asks for up to 100 rows. When Meta's usage figures pass 75 per cent of an allowance, the run pauses for as long as Meta estimates; when Meta refuses without an estimate, it waits 5 minutes.
• Read history from goes back at most 37 months, as far as Meta keeps daily figures.
• Days read again is at most 90 days.
• One run lands at most 20,000,000 records, so a long history is several runs.

A Meta Ads stream is billed like any pull: a charge for each run that does its work, and the rows it lands past what your edition includes. See what streams cost.