### Quick Start

Source: https://github.com/klosk/adloop/blob/main/README.md

Install and initialize AdLoop from source.

```bash
git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init
```

--------------------------------

### Getting Started

Source: https://github.com/klosk/adloop/blob/main/CONTRIBUTING.md

Clones the repository, navigates into the directory, and installs runtime and development dependencies.

```bash
git clone https://github.com/kLOsk/adloop.git
cd adloop
uv sync --all-extras
```

--------------------------------

### Quick Reference Commands

Source: https://github.com/klosk/adloop/blob/main/CLAUDE.md

Common commands for installing dependencies, initializing AdLoop, starting the MCP server, running tests, and syncing rules.

```bash
uv sync                  # Install dependencies
uv run adloop init       # Interactive setup wizard
uv run adloop            # Start MCP server
pytest                   # Run tests
python scripts/sync-rules.py  # Sync rules: .cursor/rules/ -> .claude/rules/
```

--------------------------------

### Install AdLoop from PyPI

Source: https://github.com/klosk/adloop/blob/main/README.md

Installs the AdLoop package and initializes it.

```bash
pip install adloop
adloop init
```

--------------------------------

### load_config Example Usage

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/config.md

Example of how to load configuration using the load_config function.

```python
from adloop.config import load_config

# Load default config
config = load_config()

# Load from custom path
config = load_config("~/my-adloop-config.yaml")
```

--------------------------------

### Setup Wizard Startup

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/server.md

Entry point for initiating the AdLoop setup wizard.

```python
# src/adloop/__init__.py::main() routes to wizard
from adloop.cli import run_init_wizard
run_init_wizard()
```

--------------------------------

### Service account example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/auth.md

Example of a service account JSON structure.

```json
# Service account example (detected automatically)
{
  "type": "service_account",
  "project_id": "my-project",
  "private_key_id": "...",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----...",
  "client_email": "adloop@my-project.iam.gserviceaccount.com",
  ...
}
```

--------------------------------

### Example AdLoop Prompts

Source: https://github.com/klosk/adloop/blob/main/README.md

Examples of questions you can ask your AI assistant using AdLoop.

```text
"How are my Google Ads campaigns performing this month?"
- "Which search terms are wasting budget? Add them as negative keywords."
- "My sign-up conversions dropped — check GA4 and Ads to find out why."
- "Draft a new responsive search ad for my main campaign."
- "Which landing pages get paid traffic but don't convert?"
- "Is my tracking set up correctly? Compare my codebase events against GA4."
- "What keywords should I target for [product]? Find ideas and estimate the budget."
- "How much budget would I need for these keywords in Germany?"
- "Create a new search campaign for [product feature] with a €20/day budget."
```

--------------------------------

### AdLoop Configuration File Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/config.md

Example structure of the AdLoop YAML configuration file.

```yaml
google:
  project_id: "my-gcp-project"
  credentials_path: "~/.adloop/credentials.json"
  token_path: "~/.adloop/token.json"

ga4:
  property_id: "123456789"

ads:
  developer_token: "developer_token_here"
  customer_id: "1234567890"
  login_customer_id: "1234567890"

safety:
  max_daily_budget: 100.00
  max_bid_increase_pct: 50
  require_dry_run: true
  log_file: "~/.adloop/audit.log"
  blocked_operations: []
```

--------------------------------

### Complete Example Configuration

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

A comprehensive example of the AdLoop configuration file, including Google Cloud, GA4, Ads, and safety settings.

```yaml
google:
  project_id: "my-company-gcp"
  credentials_path: "~/.adloop/credentials.json"
  token_path: "~/.adloop/token.json"

ga4:
  property_id: "456789012"

ads:
  developer_token: "dev-token-1a2b3c4d5e6f7g8h"
  customer_id: "9876543210"
  login_customer_id: "9876543210"

safety:
  max_daily_budget: 150.00
  max_bid_increase_pct: 25
  require_dry_run: true
  log_file: "~/.adloop/audit.log"
  blocked_operations:
    - "remove_entity"
```

--------------------------------

### get_ga4_credentials example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/auth.md

Example usage of the get_ga4_credentials function.

```python
from adloop.config import load_config
from adloop.auth import get_ga4_credentials

config = load_config()
creds = get_ga4_credentials(config)
```

--------------------------------

### get_ads_credentials example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/auth.md

Example usage of the get_ads_credentials function.

```python
from adloop.config import load_config
from adloop.auth import get_ads_credentials

config = load_config()
creds = get_ads_credentials(config)
```

--------------------------------

### Safety Configuration Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Example YAML configuration for safety guardrails and audit logging.

```yaml
safety:
  max_daily_budget: 100.00
  max_bid_increase_pct: 50
  require_dry_run: true
  log_file: "~/.adloop/audit.log"
  blocked_operations: []
```

--------------------------------

### Install AdLoop

Source: https://github.com/klosk/adloop/blob/main/README.md

Install the AdLoop package using pip.

```bash
pip install adloop
```

--------------------------------

### Install AdLoop from Source

Source: https://github.com/klosk/adloop/blob/main/README.md

Clones the AdLoop repository, synchronizes dependencies, and initializes it.

```bash
git clone https://github.com/kLOsk/adloop.git
cd adloop
uv sync
uv run adloop init
```

--------------------------------

### Python Example Usage

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/tracking.md

Example of how to use the generate_tracking_code function in Python.

```python
from adloop.config import load_config
from adloop.tracking import generate_tracking_code

config = load_config()

# Generate purchase tracking
result = generate_tracking_code(
    config,
    event_name="purchase",
    event_params={"currency": "EUR"},
    trigger="page_load",
    check_existing=True
)

print(result["code"])
print(f"\nWarnings: {result['warnings']}")
if result["already_exists"]:
    print(f"Already firing in GA4: {result['existing_count']} events")
```

--------------------------------

### Get Ad Group IDs

Source: https://github.com/klosk/adloop/blob/main/src/adloop/rules/commands/create-ad.md

Example GAQL query to retrieve ad group IDs based on campaign ID.

```sql
SELECT ad_group.id, ad_group.name FROM ad_group WHERE campaign.id = {id}
```

--------------------------------

### GAQL Date Range Examples

Source: https://github.com/klosk/adloop/blob/main/src/adloop/rules/adloop.md

Examples of how to specify date ranges in GAQL queries.

```sql
WHERE segments.date DURING LAST_7_DAYS
WHERE segments.date DURING LAST_30_DAYS
WHERE segments.date DURING THIS_MONTH
WHERE segments.date DURING LAST_MONTH
WHERE segments.date BETWEEN '2026-01-01' AND '2026-01-31'
```

--------------------------------

### Initialize AdLoop Configuration

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Command to start the interactive wizard for setting up AdLoop configuration.

```bash
adloop init
```

--------------------------------

### Google Cloud Configuration

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Example configuration for Google Cloud authentication and credentials.

```yaml
google:
  project_id: "my-gcp-project"
  credentials_path: "~/.adloop/credentials.json"
  token_path: "~/.adloop/token.json"
```

--------------------------------

### Get Ads Client Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ads.md

Return an authenticated Google Ads API client pinned to the hardcoded API version.

```python
from adloop.config import load_config
from adloop.ads.client import get_ads_client

config = load_config()
client = get_ads_client(config)
```

--------------------------------

### Google Ads API Configuration

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Example configuration for Google Ads API.

```yaml
ads:
  developer_token: "your_developer_token_here"
  customer_id: "1234567890"
  login_customer_id: "1234567890"
```

--------------------------------

### Configuration Loading

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/server.md

Example of loading the AdLoop configuration, which is done once at server startup.

```python
from adloop.config import load_config

_config = load_config()  # Global config instance, reused by all tools
```

--------------------------------

### AdLoop Install Rules Command

Source: https://github.com/klosk/adloop/blob/main/README.md

Command to install AdLoop orchestration rules and slash commands globally.

```bash
adloop install-rules
```

--------------------------------

### Example Usage of analyze_campaign_conversions

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/crossref.md

An example demonstrating how to use the analyze_campaign_conversions function and process its results.

```python
from adloop.config import load_config
from adloop.crossref import analyze_campaign_conversions

config = load_config()
result = analyze_campaign_conversions(
    config,
    date_range_start="2026-01-01",
    date_range_end="2026-01-31"
)

for campaign in result["campaigns"]:
    print(f"{campaign['campaign_name']}: {campaign['cost_per_ga4_conversion']} cost/conv")
```

--------------------------------

### Example usage of validate_tracking

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/tracking.md

An example demonstrating how to use the validate_tracking function with sample data and printing the results.

```python
from adloop.config import load_config
from adloop.tracking import validate_tracking

config = load_config()

# Assume the AI has searched the codebase and found these event names
expected = ["sign_up", "purchase", "contact", "download"]

result = validate_tracking(config, expected_events=expected)

print(f"Matched: {[e['event_name'] for e in result['matched']]}")
print(f"Missing from GA4: {result['missing_from_ga4']}")
print(f"Unexpected: {[e['event_name'] for e in result['unexpected_in_ga4']]}")

for insight in result["insights"]:
    print(f"  → {insight}")
```

--------------------------------

### Manual AdLoop Config Creation

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example of manually creating the AdLoop configuration file with essential parameters.

```bash
cat > ~/.adloop/config.yaml <<'EOF'
ga4:
  property_id: "YOUR_PROPERTY_ID"
ads:
  developer_token: "YOUR_TOKEN"
  customer_id: "YOUR_CUSTOMER_ID"
EOF
```

--------------------------------

### Launch the interactive adloop init wizard

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/server.md

Defines the function to launch the interactive setup wizard for AdLoop.

```python
def run_init_wizard() -> None:
```

--------------------------------

### MCP Server Startup

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/server.md

Entry point for starting the MCP server, routing through the server module.

```python
# src/adloop/__init__.py::main() routes to server startup
from adloop.server import mcp
mcp.run()  # FastMCP.run() starts the server
```

--------------------------------

### AdLoop Lazy Install Rules Command

Source: https://github.com/klosk/adloop/blob/main/README.md

Command to install AdLoop orchestration rules with lazy loading.

```bash
adloop install-rules --lazy
```

--------------------------------

### get_account_summaries example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ga4.md

List all GA4 accounts and properties accessible by the authenticated user.

```python
from adloop.config import load_config
from adloop.ga4.reports import get_account_summaries

config = load_config()
result = get_account_summaries(config)
for account in result["accounts"]:
    print(f"{account['display_name']}: {len(account['properties'])} properties")
```

--------------------------------

### Verify Auth & Connectivity

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Command to start the AdLoop MCP server and a note on using the health_check tool.

```bash
adloop  # starts MCP server
# Call health_check tool to verify all APIs are accessible
```

--------------------------------

### Generated JavaScript Code Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/tracking.md

An example of the JavaScript code generated by the function.

```javascript
document.addEventListener('DOMContentLoaded', function() {
  gtag('event', 'purchase', {
    'transaction_id': '<string>',
    'value': '<number>',
    'currency': 'EUR',
    'items': '<array>'
  });
});
```

--------------------------------

### Example Usage of get_tracking_events

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ga4.md

Demonstrates how to call get_tracking_events to fetch and print event data.

```python
from adloop.config import load_config
from adloop.ga4.tracking import get_tracking_events

config = load_config()
result = get_tracking_events(config)

for row in result["rows"]:
    event_name = row["eventName"]
    count = int(row["eventCount"])
    print(f"{event_name}: {count}")
```

--------------------------------

### Install patches for MCP compatibility

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/server.md

Defines the function to install patches for MCP compatibility.

```python
def install() -> None:
```

--------------------------------

### Switch Campaign to Smart Bidding

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Python code example showing how to switch a campaign's bidding strategy to MAXIMIZE_CONVERSIONS.

```python
update_campaign(
    campaign_id="...",
    bidding_strategy="MAXIMIZE_CONVERSIONS"
)
```

--------------------------------

### Python Package Entry Point

Source: https://github.com/klosk/adloop/blob/main/_autodocs/README.md

Example of how to use AdLoop's Python package for loading configuration and retrieving campaign performance.

```python
from adloop.config import load_config
from adloop.ads.read import get_campaign_performance

config = load_config()
result = get_campaign_performance(config)
```

--------------------------------

### Google Analytics 4 Configuration

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Example configuration for Google Analytics 4.

```yaml
ga4:
  property_id: "123456789"
```

--------------------------------

### get_data_client example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ga4.md

Return an authenticated Google Analytics Data API v1beta client.

```python
from adloop.config import load_config
from adloop.ga4.client import get_data_client

config = load_config()
client = get_data_client(config)
```

--------------------------------

### Override Configuration Path with Environment Variable

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Example of setting an environment variable to specify a custom configuration file path.

```bash
export ADLOOP_CONFIG=~/production-adloop-config.yaml
adloop  # starts MCP server with custom config
```

--------------------------------

### Example Usage of run_ga4_report

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ga4.md

Demonstrates how to call run_ga4_report to fetch and print GA4 data.

```python
from adloop.config import load_config
from adloop.ga4.reports import run_ga4_report

config = load_config()
result = run_ga4_report(
    config,
    dimensions=["date", "pagePath"],
    metrics=["sessions", "conversions", "bounceRate"],
    date_range_start="2026-01-01",
    date_range_end="2026-01-31"
)

for row in result["rows"]:
    print(f"{row['date']} | {row['pagePath']}: {row['sessions']} sessions")
```

--------------------------------

### INVALID_GRANT Resolution - Re-run Tool

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example command to re-run a tool to trigger re-authorization.

```text
(in Claude Code) Call health_check or any other tool
```

--------------------------------

### Execute GAQL Query Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ads.md

Execute a GAQL query and return results as a list of dictionaries.

```python
from adloop.config import load_config
from adloop.ads.gaql import execute_query

config = load_config()
rows = execute_query(
    config,
    customer_id="1234567890",
    query="""
        SELECT campaign.name, metrics.cost_micros, metrics.clicks
        FROM campaign
        WHERE segments.date DURING LAST_30_DAYS
        ORDER BY metrics.cost_micros DESC
    """
)

for row in rows:
    print(f"{row['campaign.name']}: {row['metrics.cost_micros']} micros")
```

--------------------------------

### Handle rules installation/update/uninstall commands

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/server.md

Defines the function to handle rules installation, update, and uninstall commands.

```python
def run_rules_command(command: str, args: list[str]) -> int:
```

--------------------------------

### Increase Max Daily Budget

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example of increasing the `safety.max_daily_budget` in the AdLoop configuration file.

```yaml
safety:
  max_daily_budget: 500.00
```

--------------------------------

### get_recommendations return structure

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ads.md

Example return structure for the get_recommendations function.

```python
{
    "recommendations": [
        {
            "recommendation.type": str,
            "campaign.name": str,
            "recommendation.impact.base_metrics.conversions": float | None,
            "recommendation.impact.potential_metrics.conversions": float | None,
            "estimated_improvement": float | None,
            "recommendation.description": str,
            ...
        }
    ],
    "insights": list[str],  # flagged budget/bid/strategy recommendations
    "total_recommendations": int
}
```

--------------------------------

### Draft a Campaign (Two-Step Write Workflow)

Source: https://github.com/klosk/adloop/blob/main/_autodocs/README.md

This Python code snippet demonstrates how to draft a campaign using the Adloop library. It includes steps for drafting a campaign, getting a preview, and then confirming and applying the changes.

```python
from adloop.config import load_config
from adloop.ads.write import draft_campaign, confirm_and_apply

config = load_config()

# Step 1: Draft — get a preview
preview = draft_campaign(
    config,
    campaign_name="Q2 Campaign",
    daily_budget=100.0,
    bidding_strategy="MAXIMIZE_CONVERSIONS",
    geo_target_ids=["2276"],  # Germany
    language_ids=["1001"]  # German
)

print(f"Plan ID: {preview['plan_id']}")
print(f"Preview: {preview['plan']}")

# Step 2: After user approves, confirm and apply
result = confirm_and_apply(config, plan_id=preview['plan_id'], dry_run=True)
print(f"Status: {result['status']}")
```

--------------------------------

### Change Keyword Match Type

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Python code example demonstrating how to change the match type of keywords from BROAD to PHRASE.

```python
draft_keywords(
    ad_group_id="...",
    keywords=[{"text": "my keyword", "match_type": "PHRASE"}]  # Changed from BROAD
)
```

--------------------------------

### Missing Required Parameter Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Python code demonstrating a call to `draft_campaign` missing a required parameter (`geo_target_ids`).

```python
# Wrong — missing geo_target_ids (required)
draft_campaign(
    campaign_name="Q2",
    daily_budget=100.0,
    bidding_strategy="MAXIMIZE_CONVERSIONS"
)
```

--------------------------------

### GAQL Queries for Targeting

Source: https://github.com/klosk/adloop/blob/main/src/adloop/rules/adloop.md

Examples of Google Ads Query Language (GAQL) queries to retrieve geo and language targeting information for a campaign.

```sql
SELECT campaign_criterion.location.geo_target_constant FROM campaign_criterion WHERE campaign.id = {id} AND campaign_criterion.type = 'LOCATION'
```

```sql
SELECT campaign_criterion.language.language_constant FROM campaign_criterion WHERE campaign.id = {id} AND campaign_criterion.type = 'LANGUAGE'
```

--------------------------------

### No OAuth Credentials Found Resolution - Manual Credentials

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Instructions for manually creating and placing credentials.json.

```text
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create OAuth credentials (Desktop app type)
3. Download JSON and save to `~/.adloop/credentials.json`
4. Set `google.credentials_path` in config if using non-standard location
```

--------------------------------

### Manual Configuration File Creation

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Bash command to create the configuration file manually with default values.

```bash
mkdir -p ~/.adloop
cat > ~/.adloop/config.yaml <<'EOF'
google:
  project_id: ""
  credentials_path: ""
  token_path: "~/.adloop/token.json"

ga4:
  property_id: "YOUR_PROPERTY_ID"

ads:
  developer_token: "YOUR_DEVELOPER_TOKEN"
  customer_id: "YOUR_CUSTOMER_ID"
  login_customer_id: "YOUR_MCC_ID"

safety:
  max_daily_budget: 50.00
  max_bid_increase_pct: 100
  require_dry_run: true
  log_file: "~/.adloop/audit.log"
  blocked_operations: []
EOF
```

--------------------------------

### Get Campaign Performance

Source: https://github.com/klosk/adloop/blob/main/src/adloop/rules/adloop.md

Call to get the right campaign ID for performance data.

```python
get_campaign_performance()
```

--------------------------------

### Example of Corrected Enum Value

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Demonstrates the correct usage of enum values for keywords, contrasting with an incorrect example.

```python
# Wrong
draft_keywords(keywords=[{"text": "...", "match_type": "PHRASE_EXACT"}])

# Correct
draft_keywords(keywords=[{"text": "...", "match_type": "PHRASE"}])
```

--------------------------------

### Absolute Date Range Format Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/types.md

Example of specifying absolute dates for date range parameters.

```python
date_range_start="2026-01-01"
date_range_end="2026-01-31"
```

--------------------------------

### Write Operations (Draft) Result Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/types.md

Example of the dictionary structure returned by AdLoop draft write operations.

```python
{
    "plan_id": "unique_id_abc123",
    "plan": {
        # entity details
    },
    "warnings": [],
    "message": "Ready to apply"
}
```

--------------------------------

### confirm_and_apply

Source: https://github.com/klosk/adloop/blob/main/_autodocs/endpoints.md

Executes a previously previewed plan. Defaults to a dry run unless specified otherwise.

```python
Tool: confirm_and_apply(
  plan_id: str,
  dry_run: bool = True
)
Annotation: readOnlyHint=false, destructiveHint=true
```

--------------------------------

### Write Operations (Confirm) Result Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/types.md

Example of the dictionary structure returned by AdLoop confirm and apply write operations.

```python
{
    "status": "success" | "dry_run_success" | "error",
    "plan_id": "...",
    "dry_run": true | false,
    "entities_created": 1,
    "audit_log_path": "~/.adloop/audit.log"
}
```

--------------------------------

### Read Operations Result Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/types.md

Example of the dictionary structure returned by AdLoop read operations, including rows, row count, and status fields.

```python
{
    "campaigns": [
        {
            "campaign.id": "12345",
            "campaign.name": "Q2 Campaign",
            "metrics.cost": 1234.56,
            "metrics.clicks": 789,
            "metrics.conversions": 45
        }
    ],
    "total_campaigns": 1
}
```

--------------------------------

### UNAUTHENTICATED Error Message

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example error message for unauthenticated requests.

```text
Authentication failed — Google rejected the request as unauthenticated.
```

--------------------------------

### DEVELOPER_TOKEN_INVALID Error Message

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example error message for an invalid developer token.

```text
Google Ads authentication failed — developer token is invalid.
```

--------------------------------

### FastMCP server instance initialization

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/server.md

Initializes the FastMCP server instance for AdLoop, registering all tool functions as decorators.

```python
mcp = FastMCP("AdLoop", instructions=_build_orchestration_instructions())
```

--------------------------------

### DEVELOPER_TOKEN_NOT_APPROVED Error Message

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example error message for an unapproved developer token.

```text
Google Ads authorization failed — developer token is not approved for production accounts.
```

--------------------------------

### get_campaign_performance Function Signature

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ads.md

Gets campaign-level performance metrics.

```python
def get_campaign_performance(
    config: AdLoopConfig,
    *,
    customer_id: str = "",
    date_range_start: str = "",
    date_range_end: str = ""
) -> dict
```

--------------------------------

### get_negative_keyword_list_keywords return structure

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ads.md

Example return structure for the get_negative_keyword_list_keywords function.

```python
{
    "keywords": [
        {
            "shared_criterion.keyword.text": str,
            "shared_criterion.keyword.match_type": str,
            "shared_criterion.status": str,
            "resource_id": str  # use for remove_entity
        }
    ],
    "total_keywords": int
}
```

--------------------------------

### Execute GAQL Query

Source: https://github.com/klosk/adloop/blob/main/_autodocs/README.md

Loads configuration and executes a Google Ads Query Language (GAQL) query, then prints campaign names and costs.

```python
from adloop.config import load_config
from adloop.ads.gaql import execute_query

config = load_config()
rows = execute_query(
    config,
    customer_id="1234567890",
    query="""
        SELECT campaign.name, metrics.cost_micros, metrics.clicks
        FROM campaign
        WHERE segments.date DURING LAST_30_DAYS
        ORDER BY metrics.cost_micros DESC
    """
)

for row in rows:
    print(f"{row['campaign.name']}: {int(row['metrics.cost_micros']) / 1_000_000:.2f}")
```

--------------------------------

### run_gaql

Source: https://github.com/klosk/adloop/blob/main/_autodocs/endpoints.md

Execute arbitrary GAQL query.

```python
Tool: run_gaql(
  query: str,
  customer_id: str = "",
  format: str = "table"
)
Annotation: readOnlyHint=true
```

--------------------------------

### estimate_budget Tool

Source: https://github.com/klosk/adloop/blob/main/_autodocs/endpoints.md

Forecast clicks, impressions, cost for keywords.

```python
Tool: estimate_budget(
  keywords: list[dict],
  daily_budget: float = 0,
  geo_target_id: str = "2276",
  language_id: str = "1000",
  forecast_days: int = 30,
  customer_id: str = ""
)
Annotation: readOnlyHint=true
```

--------------------------------

### INVALID_GRANT Error Message

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example error message for an expired or revoked OAuth token.

```text
Authentication failed — OAuth token expired or revoked.
```

--------------------------------

### draft_responsive_search_ad

Source: https://github.com/klosk/adloop/blob/main/_autodocs/endpoints.md

Drafts a Responsive Search Ad (RSA) with specified headlines, descriptions, and URL.

```python
Tool: draft_responsive_search_ad(
  ad_group_id: str,
  headlines: list[str | dict],
  descriptions: list[str | dict],
  final_url: str,
  customer_id: str = "",
  path1: str = "",
  path2: str = ""
)
Annotation: readOnlyHint=false
```

--------------------------------

### Display Current Configuration

Source: https://github.com/klosk/adloop/blob/main/_autodocs/configuration.md

Python code snippet to load and display current AdLoop configuration values.

```python
from adloop.config import load_config

config = load_config()
print(f"GA4 Property: {config.ga4.property_id}")
print(f"Ads Customer: {config.ads.customer_id}")
print(f"Max Budget: {config.safety.max_daily_budget}")
print(f"Config File: {config.source_path}")
```

--------------------------------

### Write Tool Response (Preview)

Source: https://github.com/klosk/adloop/blob/main/_autodocs/types.md

Draft tools return a preview with plan ID.

```json
{
    "plan_id": str,  # unique ID for this draft
    "plan": dict,  # preview of what will be created/modified
    "warnings": list[str],  # safety or validation warnings
    "message": str,  # human-readable summary
    "dry_run": bool  # always true for preview
}
```

--------------------------------

### Validate Tracking Function

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

An example of how to use the `validate_tracking` function to check for expected conversion events.

```python
validate_tracking(
    expected_events=["purchase", "sign_up"],
    date_range_start="7daysAgo"
)
```

--------------------------------

### Get Negative Keywords

Source: https://github.com/klosk/adloop/blob/main/src/adloop/rules/adloop.md

Call to retrieve existing blocked negative keywords.

```python
get_negative_keywords()
```

--------------------------------

### Running Tests

Source: https://github.com/klosk/adloop/blob/main/CONTRIBUTING.md

Executes the test suite using pytest.

```bash
uv run pytest
```

--------------------------------

### Get Search Terms

Source: https://github.com/klosk/adloop/blob/main/src/adloop/rules/adloop.md

Call to retrieve current search term data.

```python
get_search_terms()
```

--------------------------------

### DEVELOPER_TOKEN_INVALID Hint

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Hint for resolving the invalid developer token error.

```text
Update `ads.developer_token` in `~/.adloop/config.yaml` with the token from your Google Ads 
manager account API Center. OAuth is working if GA4 tools succeed.
```

--------------------------------

### Normalize Customer ID Example

Source: https://github.com/klosk/adloop/blob/main/_autodocs/api-reference/ads.md

Strip dashes from customer ID for API calls.

```python
def normalize_customer_id(customer_id: str) -> str:
    """Strip dashes from customer ID for API calls."""
    return customer_id.replace("-", "")
```

--------------------------------

### Remove Operation from Blocklist

Source: https://github.com/klosk/adloop/blob/main/_autodocs/errors.md

Example of modifying the AdLoop configuration file to remove an operation from the `safety.blocked_operations` list.

```yaml
safety:
  blocked_operations: []  # Removed the blocked operation
```