# 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:
```bash
uv sync
```

2. Configure your Meta API credentials:
```bash
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](https://developers.facebook.com/)
   - 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)**
   ```bash
   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](https://developers.facebook.com/tools/explorer/)
   - Add it manually to `.env` as `META_ACCESS_TOKEN`

## Usage

Run the insights grabber:
```bash
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:**
```bash
uv run python src/meta_api_grabber/auth.py
```

**Grab Insights Data:**
```bash
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:
```json
{
  "account": { ... },
  "campaigns": { ... },
  "ad_sets": { ... },
  "summary": { ... }
}
```