Meta Ads
Paid Facebook and Instagram. You sign in with your Meta account, tick which ad accounts belong to this workspace, and that is it. Nothing to type and nothing to request from Meta support.
Start
ConnectMeta login, nothing to type
Under Sources · Connect new source · Meta Ads, click the card. A Facebook window opens, you sign in and approve. If nothing happens when you click, it is the pop-up blocker.
caOS then asks Which accounts belong to this workspace?, with everything pre-ticked. Tick yours and confirm. All that is left is the tag.
Untick what is not yours. The authorisation sees everything the person who clicked can reach on Meta, and at an agency that is the entire client book. A new workspace has been born with almost a hundred accounts belonging to another company. What you do not tick does not come in, and nothing is changed on Meta's side.
Whoever clicks decides what appears. The list comes from that person's access. If they cannot see the account in Ads Manager, they will not see it here. Choose who connects before you open the screen.
Your credential, and what happens to it
Connect once and you are connected. The credential renews itself, indefinitely. You do not need a date in the calendar and you do not need to reconnect periodically.
There is only one way the connection drops: someone revokes access on the platform side (password changed, person removed from the account, authorisation cancelled). The account then shows up under Lost connections and reconnecting fixes it, keeping the tags it already had.
Your credential is encrypted end to end. It is encrypted before it is stored, and the key does not live in the database, so even database access does not reveal it. Nobody at caOS, and not you either, can read the credential back after it is saved. The screen only shows that it exists and is valid.
Only the metrics you asked for are read. caOS does not write to your ad account in order to extract data, and it stores no personal data about who saw the ad. Processing follows Brazilian data protection law (LGPD), and deletion is yours: revoking the connection erases the stored credential.
Reference
Metrics and dimensionswhat each field means
The performance table carries 110 fields. You do not need to know them all. Below are the ones that show up in real reports, with the name they take in Pacer and in the spreadsheet.
Core metrics13 of 110
| API field | What it is | Where it shows up |
|---|---|---|
| spend | How much was spent, already in the account currency. | Spend in Pacer. Column spend in the spreadsheet. |
| impressions | How many times the ad was shown. | Impressions. |
| clicks | Every click, including those that do not go to the site. | Clicks. For clicks that leave to the site, use inline_link_clicks. |
| reach | Distinct people who saw the ad. | Reach. Never sum it across days or ads: the same person would count twice. |
| frequency | How many times, on average, each person saw it. | Frequency. Pacer recomputes it as impressions ÷ reach for the period rather than summing the field. |
| inline_post_engagement | Interactions with the post. | Engagement. |
| actions | A list of every action type, not a single number. | Conversions come from here. Website purchase is offsite_conversion.fb_pixel_purchase. |
| video_15_sec_watched_actions | Video watched for 15 seconds or to the end. | This is what becomes video view in caOS reports. |
| video_thruplay_watched_actions | ThruPlay, the metric Meta's own interface shows. | Only available in tables you build. A different number from the one above: pick one and do not mix. |
| video_p25_watched_actions | Reached 25% of the video. There are also 50, 75, 95 and 100. | Use it for a retention curve. |
| cpm | Cost per thousand impressions. | CPM. Pacer recomputes it from the sums instead of averaging averages. |
| cpc | Cost per click. | CPC, also recomputed. |
| ctr | Clicks ÷ impressions. | CTR, also recomputed. |
Dimensions5
| API field | What it is | Where it shows up |
|---|---|---|
| date_start | The day of the row. | Every performance table comes by day. |
| campaign_name | Campaign name. | Comes with campaign_id, which is what survives a rename. |
| adset_name | Ad set name. | With adset_id. |
| ad_name | Ad name. | With ad_id. |
| account_currency | Account currency. | Check it before summing accounts from different countries. |
Report parameters
The fields above say what comes back. These parameters say how: they decide the grain of the row, the period it covers and what counts as a conversion. Two reports from the same account showing different numbers almost always differ here.
| Parameter | What it changes | Values |
|---|---|---|
| level | The grain of each row. | Account, campaign, ad set or ad. caOS default: ad. |
| time_increment | Whether a row covers one day or a whole period. | 1 day, 7 days, month, or the entire period in a single row. Default: 1 day. |
| breakdowns | The breakdown, which multiplies rows. | 12 values: age, gender, country, region, DMA, platform, placement, impression and action device, product, hour and frequency band. |
| action_breakdowns | How the actions column splits. | 15 values, among them action type, destination, reaction, video type, sound and carousel card. Default: action_type. |
| action_attribution_windows | Which window counts a conversion. | View and click at 1, 7 or 28 days. caOS default: 1d_view + 7d_click, the same as Meta's own. |
| action_report_time | Which day the conversion lands on. | impression books it on the ad's day, conversion on the purchase day, mixed combines. Default: mixed. |
Everything you can pull
The tables above are what most reports use, but you are not stuck with them. The full Meta catalogue has 11 tables and 427 fields, and you choose what goes in when you build the source. What is marked used by default is what the example source uses; the rest is available just the same.
The list below comes from the Xtractor catalogue itself, the same one the new source screen reads. If a field is here, the screen offers it.
adsinsights_default used by default110 fields
account_currency, account_id, account_name, action_values, actions, ad_click_actions, ad_id, ad_impression_actions, ad_name, adset_id, adset_name, attribution_setting, auction_bid, auction_competitiveness, auction_max_competitor_bid, average_purchases_conversion_value, buying_type, campaign_id, campaign_name, canvas_avg_view_percent, canvas_avg_view_time, catalog_segment_actions, catalog_segment_value, catalog_segment_value_mobile_purchase_roas, catalog_segment_value_omni_purchase_roas, catalog_segment_value_website_purchase_roas, clicks, conversion_rate_ranking, conversion_values, conversions, converted_product_quantity, converted_product_value, cost_per_15_sec_video_view, cost_per_2_sec_continuous_video_view, cost_per_action_type, cost_per_ad_click, cost_per_conversion, cost_per_estimated_ad_recallers, cost_per_inline_link_click, cost_per_inline_post_engagement, cost_per_outbound_click, cost_per_thruplay, cost_per_unique_action_type, cost_per_unique_click, cost_per_unique_inline_link_click, cost_per_unique_outbound_click, cpc, cpm, cpp, created_time, ctr, date_start, date_stop, engagement_rate_ranking, estimated_ad_recall_rate, estimated_ad_recallers, frequency, full_view_impressions, full_view_reach, impressions, inline_link_click_ctr, inline_link_clicks, inline_post_engagement, instant_experience_clicks_to_open, instant_experience_clicks_to_start, instant_experience_outbound_clicks, marketing_messages_delivery_rate, marketing_messages_link_btn_click_rate, marketing_messages_quick_reply_btn_click_rate, marketing_messages_read_rate, marketing_messages_website_purchase_values, mobile_app_purchase_roas, objective, onsite_conversion_messaging_detected_purchase_deduped, optimization_goal, outbound_clicks, outbound_clicks_ctr, purchase_roas, qualifying_question_qualify_answer_rate, quality_ranking, reach, shops_assisted_purchases, social_spend, spend, unique_actions, unique_clicks, unique_ctr, unique_inline_link_click_ctr, unique_inline_link_clicks, unique_link_clicks_ctr, unique_outbound_clicks, unique_outbound_clicks_ctr, updated_time, video_15_sec_watched_actions, video_30_sec_watched_actions, video_avg_time_watched_actions, video_continuous_2_sec_watched_actions, video_p100_watched_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p95_watched_actions, video_play_actions, video_play_curve_actions, video_play_retention_0_to_15s_actions, video_play_retention_20_to_60s_actions, video_play_retention_graph_actions, video_time_watched_actions, website_ctr, website_purchase_roas
adaccounts80 fields
account_id, timezone_id, business_name, account_status, age, amount_spent, balance, business_city, business_country_code, business_street, business_street2, can_create_brand_lift_study, capabilities, created_time, currency, disable_reason, end_advertiser, end_advertiser_name, has_migrated_permissions, id, is_attribution_spec_system_default, is_direct_deals_enabled, is_in_3ds_authorization_enabled_market, is_notifications_enabled, is_personal, is_prepay_account, is_tax_id_required, min_campaign_group_spend_cap, min_daily_budget, name, offsite_pixels_tos_accepted, owner, spend_cap, tax_id_status, tax_id_type, timezone_name, timezone_offset_hours_utc, agency_client_declaration_agency_representing_client, agency_client_declaration_client_based_in_france, agency_client_declaration_client_city, agency_client_declaration_client_country_code, agency_client_declaration_client_email_address, agency_client_declaration_client_name, agency_client_declaration_client_postal_code, agency_client_declaration_client_province, agency_client_declaration_client_street, agency_client_declaration_client_street2, agency_client_declaration_has_written_mandate_from_advertiser, agency_client_declaration_is_client_paying_invoices, business_manager_block_offline_analytics, business_manager_created_by, business_manager_created_time, business_manager_extended_updated_time, business_manager_is_hidden, business_manager_link, business_manager_name, business_manager_payment_account_id, business_manager_primary_page, business_manager_profile_picture_uri, business_manager_timezone_id, business_manager_two_factor_type, business_manager_updated_by, business_manager_update_time, business_manager_verification_status, business_manager_vertical, business_manager_vertical_id, business_manager_manager_id, extended_credit_invoice_group_id, extended_credit_invoice_group_auto_enroll, extended_credit_invoice_group_customer_po_number, extended_credit_invoice_group_email, extended_credit_invoice_group_emails, extended_credit_invoice_group_name, business_state, io_number, media_agency, partner, salesforce_invoice_group_id, business_zip, tax_id
creatives52 fields
id, account_id, actor_id, applink_treatment, asset_feed_spec, authorization_category, body, branded_content_sponsor_page_id, bundle_folder_id, call_to_action_type, categorization_criteria, category_media_source, degrees_of_freedom_spec, destination_set_id, dynamic_ad_voice, effective_authorization_category, effective_instagram_media_id, effective_object_story_id, enable_direct_install, image_hash, image_url, instagram_actor_id, instagram_permalink_url, instagram_story_id, link_destination_display_url, link_og_id, link_url, messenger_sponsored_message, name, object_id, object_store_url, object_story_id, object_story_spec, object_type, object_url, page_link, page_message, place_page_set_id, platform_customizations, playable_asset_id, source_instagram_media_id, status, template_url, thumbnail_id, thumbnail_url, title, url_tags, use_page_actor_override, video_id, template_url_spec, product_set_id, carousel_ad_link
adsets43 fields
name, end_time, billing_event, campaign_attribution, destination_type, is_dynamic_creative, lifetime_imps, multi_optimization_goal_weight, optimization_goal, optimization_sub_event, pacing_type, recurring_budget_semantics, source_adset_id, status, targeting_optimization_types, use_new_app_click, promoted_object, id, account_id, updated_time, daily_budget, budget_remaining, effective_status, campaign_id, created_time, start_time, lifetime_budget, bid_info, adlabels, attribution_spec, learning_stage_info, configured_status, asset_feed_id, daily_min_spend_target, daily_spend_cap, instagram_actor_id, review_feedback, rf_prediction_id, bid_amount, bid_strategy, targeting, lifetime_min_spend_target, lifetime_spend_cap
advideos38 fields
id, account_id, ad_breaks, backdated_time, backdated_time_granularity, content_category, content_tags, created_time, custom_labels, description, embed_html, embeddable, event, format, from_object, icon, is_crosspost_video, is_crossposting_eligible, is_episode, is_instagram_eligible, is_reference_only, length, live_status, music_video_copyright, permalink_url, place, post_views, premiere_living_room_status, privacy, published, scheduled_publish_time, source, status_processing_progress, status_value, title, universal_video_id, updated_time, views
campaigns35 fields
name, objective, id, account_id, effective_status, buying_type, can_create_brand_lift_study, can_use_spend_cap, configured_status, has_secondary_skadnetwork_reporting, is_skadnetwork_attribution, primary_attribution, smart_promotion_type, pacing_type, source_campaign_id, boosted_object_id, special_ad_categories, special_ad_category, status, topline_id, spend_cap, budget_remaining, daily_budget, start_time, stop_time, updated_time, created_time, adlabels, budget_rebalance_flag, bid_strategy, ad_strategy_group_id, ad_strategy_id, lifetime_budget, last_budget_toggling_time, special_ad_category_country
customaudiences21 fields
account_id, id, approximate_count_lower_bound, approximate_count_upper_bound, time_updated, time_created, time_content_updated, customer_file_source, data_source, delivery_status, description, lookalike_spec, is_value_based, operation_status, permission_for_actions, pixel_id, retention_days, subtype, rule_aggregation, opt_out_link, name
ads19 fields
bid_type, account_id, campaign_id, adset_id, bid_amount, bid_info, status, creative, id, updated_time, created_time, name, effective_status, last_updated_by_app_id, recommendations, source_ad_id, tracking_specs, conversion_specs, configured_status
adimages16 fields
id, account_id, created_time, creatives, hash, height, is_associated_creatives_in_adgroups, name, original_height, original_width, permalink_url, status, updated_time, url, url_128, width
customconversions8 fields
account_id, id, name, creation_time, business, is_archived, is_unavailable, last_fired_time
adlabels5 fields
id, account, created_time, updated_time, name
And the table you design
Beyond the ready-made tables, Meta is the only connector with a table builder: you choose the level (account, campaign, ad set or ad), whether it aggregates by day, week, month or the whole period, and which fields go in. The picker offers 119 fields across eight categories: identification, configuration, delivery and cost, clicks, engagement, video, conversions and actions, and quality and estimates.
That is 23 dimensions, 68 metrics and 28 action types. On top of those come the breakdowns, which multiply the rows: age, gender, country, region, DMA, platform, placement, impression device, action device, product, hour and frequency band. And the action breakdowns, which split the conversions column by type, destination, reaction, video type, sound, carousel card and more.
The screen validates the combination before calling the API, because Meta only accepts certain breakdown permutations. If it refuses, that is the platform's own rule, and removing one breakdown at a time resolves it.
Every breakdown multiplies the rows, and Meta only accepts certain combinations: frequency requires reach, an hourly breakdown refuses video fields. The screen warns you before it calls the API.
Output
Where the data landsa spreadsheet and a warehouse are different jobs
Google Sheets
For building a report by hand
You pick the columns and the cut, and every sync refreshes the same tab. There is no catalogue to study: what you tick becomes a column, in the order you ticked it.
Start with spend, impressions, clicks and the campaign name. That covers 90% of reports, and you can add the rest later without redoing anything.
BigQuery
For modelling on top
11 standard tables plus the ones you design. Performance
lives in adsinsights_default: one row per ad per day. The rest
are structure (accounts, campaigns, ad sets, ads, creatives, images,
videos, labels, audiences and conversions) and are a snapshot, not a time
series.
Tables you design become their own table in the destination: you choose the level, the aggregation and the fields.
Creatives at presentation size. Meta's API returns the creative image as a thumbnail, and about half of all creatives (video, carousel, dynamic) do not even carry the large version. It is good enough to check a creative, not to put one in a client report.
On the Enterprise plan caOS requests the high resolution image at the source and keeps its own copy of every creative, with a stable link. The creative goes into the report at presentation size, and stays reachable even after the ad stops running.
Trust
Data freshnesswhy yesterday's number still moves
Ad platforms rewrite the past. A conversion attributed days later, revised spend, a corrected row: Tuesday's number changes on Thursday. If the extraction only ever brought the newest day, your spreadsheet would freeze at the first value and drift away from the platform with nobody noticing.
So caOS re-reads the last 28 days on every sync and rewrites what changed. Older history stays in the destination and is not touched. In practice: what sits in your spreadsheet or your warehouse is what the platform says today, not what it said on the day of the first load.
The day closes in the ad account's time zone, not yours. When a client moves to a new account in a different time zone, the day boundary shifts: the period total does not change, but a specific day's number does.
Detail
Good to knowwhat usually raises questions
A conversion is not a column, it is a row inside actions.
Website purchase is offsite_conversion.fb_pixel_purchase;
omni_purchase adds site, app and store together and gives a bigger
number. In a spreadsheet, actions arrives as the sum of every
action type, not as the isolated conversion you want.
Two video metrics with similar names. The standard table carries the 15 second one; the table you build offers ThruPlay and does not offer the 15 second one. They are different numbers. Pick one and do not mix them across reports.
Reach does not add up. Summing reach across two days, or two ads, counts the same person twice. For reach over a period, ask for the whole period at once.
Support
When it failsthe message and what to do
“Authorisation was not completed.” Access was denied, or the window was closed before approving. Start again from the caOS button.
“Your connection session expired.” The link is valid for 10 minutes and works once. Start again, without reusing an old window.
Connected, but no account appears. On Meta the account lookup runs after the connection. Wait a few seconds and reload. If it stays empty, look at the access of whoever authorised.
“Meta account without a valid token.” The credential that brought that account was revoked. Reconnecting fixes it, and the account returns with the tags it had.
“Invalid breakdown combination.” Remove one breakdown at a time until the screen is happy again.
“Paused automatically after 5 consecutive failures.” The connection stops by itself after five errors in a row. Fix what the last error pointed at and reactivate.