Meta's Marketing API is a mess — deprecations every quarter, undocumented field changes, attribution windows that contradict themselves. But it's also the only way to get CTR, ROAS, and spend into a unified dashboard alongside Google Ads and organic channel data. Velocity X pulls from Meta's Insights API, handles token refresh, manages ad-account scopes, and stacks conversion events with the right attribution window. Here's how.
Long-Lived Access Tokens and the 60-Day Refresh Dance
Meta's Marketing API uses short-lived tokens (60 minutes) and long-lived tokens (60 days). If you've been refreshing every hour, stop. Velocity X requests the long-lived variant on the initial OAuth handshake with scopes ads_management, ads_read, and business_management. The long-lived token ships back in the OAuth response; we store it encrypted in Postgres bytea hex (same pattern as HubSpot above). A cron job fires 59 days after receipt, refreshes the token server-to-server before expiry, and pushes the new value back to the row. Users never see "reconnect your Meta account" unless the refresh call fails 3 times in a row.
POST https://graph.instagram.com/v20.0/oauth/access_token
?client_id=YOUR_APP_ID
&client_secret=YOUR_APP_SECRET
&grant_type=fb_exchange_token
&fb_exchange_token=SHORT_LIVED_TOKENMeta's docs say "valid for 60 days"; in practice, we've seen tokens rot after 55 days on a small fraction of accounts. Velocity X errs conservative: refresh at 58 days.
Business Account Selection and Ad-Account Scope
After OAuth approval, Velocity X fetches the list of ad accounts the user has access to by querying the business manager node. Most users have one; enterprise clients have 10+. Each ad account has its own insights API endpoint and its own campaign/ad hierarchy. Velocity X shows a dropdown on first setup: "Which ad account do you want to track?" Once selected, all insights queries hit that account's /insights endpoint. If the user adds a second account later, they create a second Velocity X integration — one long-lived token per ad account, stored separately. This avoids scope pollution and makes revocation per-account, not org-level.
Insights API Time Series and Batched Queries
The Insights API returns metrics (impressions, clicks, spend, conversions) aggregated by time bucket. Velocity X queries the last 90 days of data daily at 02:00 UTC (when Meta has finished processing the prior day's numbers). Each request specifies time_range={since, until}, granularity=day, and a metric list: impressions,clicks,spend,actions. The API returns ~90 rows per campaign (one row per day), so if you're tracking 50 campaigns, that's 4,500 data points. Velocity X batches these into a single request with batch=true; Meta returns all campaigns' insights in one response, avoiding 50 separate API calls.
GET /v20.0/{ad_account_id}/insights
?fields=impressions,clicks,spend,actions
&time_range={"since":"2026-06-01","until":"2026-06-12"}
&granularity=day
&level=campaignThe actions field is a nested JSON array: [{action_type: "purchase", value: 3}, {action_type: "add_to_cart", value: 12}]. Velocity X unpacks this and stores each action type separately, keyed by campaign + action + date. Store these in a Supabase table with columns (ad_account_id, campaign_id, date, metric_type, value) for fast lookups at dashboard render time.
Attribution Windows and the Messy Reality
Meta reports conversions in three windows: 1-day, 7-day, and 28-day click attribution. The Insights API defaults to 28-day, which is fine for brand awareness but useless for SaaS CTR benchmarks (you need 1-day to see signal). Velocity X lets you override the attribution window at query time with the attribution_windows parameter. Set it to ["1d_click"] for e-commerce (fast feedback loop), ["7d_click"] for mid-funnel (lead gen), or ["28d_click"] for awareness. The SLT dashboard shows 7-day by default; execs can flip it in a dropdown.
Meta's dark secret: the same campaign's conversion count differs by 20–40% depending on which window you ask for, because click attribution is probabilistic and Meta's algo adjusts based on time decay. Always document which window you're using when comparing Meta to Google — they use different models entirely.
Handling Meta API Deprecations
Meta deprecates Insights API fields every major version (v19, v20, v21). The actions field used to return a flat array; now it's nested. The video_play_actions field was sunset in v20.0. Velocity X hardcodes the API version in every request (/v20.0/) and pins it in a config file. When Meta announces a deprecation 90 days ahead, we schedule an upgrade sprint, test against the new version in a sandbox ad account, and flip the switch. You can't query old versions once they're deprecated, so missing the window is a production incident.
Frequently Asked Questions
What's the difference between the Insights API and the Ads API?
Insights = read-only metrics (spend, clicks, conversions). Ads = campaign/ad creation, budget allocation, audience targeting (write operations). Velocity X only uses Insights. Avoid the Ads API unless you're automating budget shifts.
Does the 60-day token expiry apply to all ad accounts or just one?
One token per business manager + one user. If you have multiple ad accounts, you have multiple tokens — but they're all long-lived and refresh in sync.
Can I pull conversion data without pixel instrumentation?
No. The actions field on the Insights API requires a Meta Pixel or Conversions API live on your site. If you're not tracking conversions, all you get is impressions, clicks, and spend — no ROAS, no attribution.
Why does my Insights API response lag by 24 hours?
Meta's data warehouse updates once daily at ~02:00 UTC. Queries for "today" return incomplete data. Velocity X always queries up to yesterday and shows current spend (estimated by dividing daily avg by 24) as an asterisked note.
How do I export the dashboard data?
Velocity X generates a CSV snapshot once daily and stores it in Netlify Blobs. You can download the last 90 days of exports from the dashboard's admin page, or integrate with your BI tool via our REST API.
The Bottom Line
Meta's Marketing API is powerful once you stop fighting it: long-lived tokens remove refresh overhead, batched insights queries cut API calls by 95%, and attribution window overrides let you compare apples-to-apples with Google. The real skill is staying ahead of Meta's deprecation cycle — set up version pinning, test early, and subscribe to their breaking-changes feed. See pricing or dive deeper into our unified marketing analytics guide.