Meta Instagram Ads

Install

See the Install guide for the full setup, including Windows PowerShell.

curl -fsSL https://install.skippr.io/install.sh | shClick to copy

Installing Skippr means accepting the Skippr EULA.

Extracts curated daily insights from the Meta Marketing API for Instagram placement traffic. Each namespace is one bronze grain with replace-by-date landing semantics (replace_partition on date).

How it works

1. Authenticates with a long-lived access token or OAuth refresh credentials.
2. For each selected stream, requests one calendar day per API call (time_increment=1).
3. Filters to Instagram publisher traffic when instagram_filter is enabled (default).
4. Paginates through paging.next until all insight rows are retrieved.
5. Skips the trailing processing_lag_days (default 1).
6. Re-syncs lookback_days (default 3) of mature dates; replace_partition on date overwrites revised metrics.

Discover sampling (automatic)

skippr discover stays fast even when stream_profile: full is configured:

• Samples the last 3 calendar days of meta_instagram_ads.account_daily only
• Does not load checkpoints or apply lookback
• Namespace contracts still reflect your configured profile (e.g. all five namespaces on full)

Full historical sync and all grains run on skippr sync.

Configuration

Engine skippr.yml (runtime plugin):

pipelines:
  picnic_meta_ig:
    data_source: data_sources.meta_ig
    data_sink: data_sinks.athena

data_sources:
  meta_ig:
    MetaInstagramAds:
      ad_account_id: "${META_AD_ACCOUNT_ID}"
      access_token: "${META_INSTAGRAM_ADS_ACCESS_TOKEN}"
      start_date: "2024-01-01"
      stream_profile: full
      lookback_days: 3
      instagram_filter: true

Public skippr.yaml (via skippr connect):

source:
  kind: meta_instagram_ads
  ad_account_id: "${META_AD_ACCOUNT_ID}"
  access_token: "${META_INSTAGRAM_ADS_ACCESS_TOKEN}"
  start_date: "2024-01-01"
  stream_profile: full

Field	Default	Description
ad_account_id	(required)	Meta ad account ID (with or without act_ prefix)
access_token		Long-lived user/system token (${META_INSTAGRAM_ADS_ACCESS_TOKEN})
oauth_token_url		OAuth token endpoint (use with refresh credentials)
oauth_client_id		Meta app client ID
oauth_client_secret		Meta app client secret
oauth_refresh_token		Refresh token for Marketing API access
api_version	v21.0	Graph API version segment
start_date	(required)	First date to sync (YYYY-MM-DD)
end_date		Last date; omit to sync through yesterday minus lag
stream_profile	full	minimal (1), standard (3), or full (5 namespaces)
streams	profile set	Comma-separated namespaces; overrides profile when set
lookback_days	3	Mature days to re-fetch each run
processing_lag_days	1	Skip syncing the last N calendar days
instagram_filter	true	Restrict insights to publisher_platform=instagram

Stream profiles

Profile	Namespaces	Use case
full	5	Production default (all daily grains)
standard	3	Account + campaign + ad set
minimal	1	Discover / CI (account_daily only)

Bronze catalog (stream_profile: full)

Namespace	Level	Notes
meta_instagram_ads.account_daily	Account	Org-wide Instagram insights
meta_instagram_ads.campaign_daily	Campaign	Per-campaign daily metrics
meta_instagram_ads.adset_daily	Ad set	Per-ad-set daily metrics
meta_instagram_ads.ad_daily	Ad	Per-ad daily metrics
meta_instagram_ads.campaign_placement_daily	Campaign	breakdowns=platform_position

Rows include ad_account_id, date, grain IDs (campaign_id, adset_id, ad_id), and Meta insight fields (e.g. impressions, clicks, spend) as returned by the API.

Landing semantics

Daily Meta insights are mutable. This source uses replace_partition on date with lookback_days as the refresh window.

See Source landing semantics.

CLI

skippr connect source meta-instagram-ads \
  --ad-account-id "${META_AD_ACCOUNT_ID}" \
  --access-token "${META_INSTAGRAM_ADS_ACCESS_TOKEN}" \
  --start-date 2024-01-01 \
  --stream-profile full \
  --lookback-days 3

Authentication

Provide either:

• access_token / META_INSTAGRAM_ADS_ACCESS_TOKEN — long-lived Marketing API token with ads_read (and related) permissions, or
• OAuth refresh — oauth_token_url, oauth_client_id, oauth_client_secret, and oauth_refresh_token (defaults to Meta’s token endpoint when configured in skippr.yml).

Required env vars (typical):

• META_AD_ACCOUNT_ID
• META_INSTAGRAM_ADS_ACCESS_TOKEN

Recommended destination

Athena (S3 + Glue) with pipeline transform:

pipelines:
  picnic_meta_ig:
    transform:
      batch_time_fields: [date]

Bronze paths look like bronze/meta_instagram_ads.campaign_daily/date=2024-01-15/. Run skippr discover after the first sync.

Troubleshooting

Symptom	Fix
Token / 401 errors	Regenerate a long-lived token; confirm ads_read on the ad account
Empty streams	Verify campaigns ran on Instagram; check instagram_filter
Rate limits (429)	Plugin retries with backoff; reduce parallel jobs if needed
Slow discover	Expected — discover only samples 3 days of account_daily; use skippr sync for full history
Stale metrics	Confirm replace_partition; increase lookback_days

Offline dev: set SKIPPR_META_INSTAGRAM_ADS_FIXTURE_DIR to JSON fixtures (account_insights.json, campaign_insights.json, etc.).

Next steps

• Source landing semantics
• Athena destination