meta_api_grabber/README.md

Meta API Grabber

Async script to grab ad insights data from Meta's Marketing API with conservative rate limiting.

Features

• OAuth2 Authentication - Automated token generation flow
• Async/await architecture for efficient API calls
• Conservative rate limiting (2s between requests, 1 concurrent request)
• Multi-level insights - Account, campaign, and ad set data
• JSON output with timestamps
• Configurable date ranges

Setup

1. Install dependencies using uv:

uv sync

2. Configure your Meta API credentials:

cp .env.example .env

3. Edit .env and add your App ID, App Secret, and Ad Account ID:

   • Get your App credentials from Meta for Developers
   • Find your ad account ID in Meta Ads Manager (format: act_1234567890)

4. Get an access token (choose one method):

   Option A: OAuth2 Flow (Recommended)

   uv run python src/meta_api_grabber/auth.py
   

   This will:

   • Generate an authorization URL
   • Walk you through the OAuth2 flow
   • Offer to save the access token to .env automatically

   Option B: Manual Token

   • Get a token from Graph API Explorer
   • Add it manually to .env as META_ACCESS_TOKEN

Usage

Run the insights grabber:

uv run python src/meta_api_grabber/insights_grabber.py

This will:

• Fetch insights for the last 7 days
• Grab account-level, campaign-level (top 10), and ad set-level (top 10) data
• Save results to data/meta_insights_TIMESTAMP.json

Authentication Scripts

Get OAuth2 Access Token:

uv run python src/meta_api_grabber/auth.py

Grab Insights Data:

uv run python src/meta_api_grabber/insights_grabber.py

Data Collected

Account Level

• Impressions, clicks, spend
• CPC, CPM, CTR
• Reach, frequency
• Actions and cost per action

Campaign Level (top 10)

• Campaign name and ID
• Impressions, clicks, spend
• CTR, CPC

Ad Set Level (top 10)

• Ad set name and ID
• Impressions, clicks, spend
• CTR, CPM

Rate Limiting

The script is configured to be very conservative:

• 2 seconds delay between API requests
• Only 1 concurrent request at a time
• Limited to top 10 campaigns and ad sets

You can adjust these settings in the MetaInsightsGrabber class if needed.

Output

Data is saved to data/meta_insights_TIMESTAMP.json with the following structure:

{
  "account": { ... },
  "campaigns": { ... },
  "ad_sets": { ... },
  "summary": { ... }
}