Skip to content

Conversation

pjatx
Copy link

@pjatx pjatx commented Aug 14, 2025

Problem

This connector has some defaults / assumptions that are baked in which cause some unexpected and confusing behavior. Some background: https://dlthub-community.slack.com/archives/C04DQA7JJN6/p1754597588552409

Essentially, if you hit the insights API and include action breakdowns / breakdowns, you might get back very different numbers of purchases, add to carts, etc then what you would observe in the dashboard. It's not apparent that there have been breakdowns applied in the API responses either, so it causes the user to have to debug the API calls, tweak some things, run the pipeline, and repeat until they figure this out just based on trial and error.

Removing the defaults I think would make sense for the vast majority of folks trying to load simple ads and insights data. The more advanced users can specify these options in their more complex use cases and are probably already more familiar with the API and why they would need these breakdowns for their specific case.

Summary

  • Remove automatic inclusion of breakdowns and action_breakdowns parameters in Facebook Ads insights requests
  • Update sample pipeline to demonstrate explicit usage with commented examples
  • Clean up unused constants and imports

Changes Made

Core Changes:

  • Modified facebook_insights_source() to default breakdowns and action_breakdowns to None instead of ads_insights and ALL_ACTION_BREAKDOWNS
  • Updated query building logic to conditionally include these parameters only when explicitly provided by users
  • Updated function documentation to reflect new default behavior

Code Cleanup:

  • Removed unused ALL_ACTION_BREAKDOWNS import from __init__.py
  • Deleted unused ALL_ACTION_BREAKDOWNS constant from settings.py

Documentation & Examples:

  • Added new load_insights_with_breakdowns() example function in facebook_ads_pipeline.py
  • Included commented examples showing how to add action breakdowns when needed
  • Updated docstrings to clarify that both parameters now default to None

Impact

####Before:
Users would see action counts inconsistent from what's reported by default in Facebook Ads Manager

After:

Users must explicitly specify breakdowns and action_breakdowns parameters if they want them included in their requests.

Example Usage

Basic insights (no breakdowns)

  i_basic = facebook_insights_source(initial_load_past_days=7)

With age/gender breakdowns

  i_with_breakdowns = facebook_insights_source(
      initial_load_past_days=7,
      breakdowns="ads_insights_age_and_gender"
  )

With custom action breakdowns

  i_with_actions = facebook_insights_source(
      initial_load_past_days=7,
      action_breakdowns=["action_type", "action_target_id"]
  )

This change gives users full control over their Facebook Ads insights requests and reduces unnecessary API complexity for users who don't need breakdown data.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants