# Google Ads Query

> |

- **Type:** Skill
- **Install:** `agentstack add skill-fourteenwm-ppc-ai-skills-google-ads-query`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fourteenwm](https://agentstack.voostack.com/s/fourteenwm)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fourteenwm](https://github.com/fourteenwm)
- **Source:** https://github.com/fourteenwm/ppc-ai-skills/tree/main/google-ads-query

## Install

```sh
agentstack add skill-fourteenwm-ppc-ai-skills-google-ads-query
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Google Ads Query Skill

Query Google Ads API data, save to CSV, and return minimal output (file path + row count only).

## Purpose

This skill implements the **CSV-first pattern** for context-efficient analysis:
1. Query API data
2. Save to CSV file (data stays outside context)
3. Return only file path + row count
4. Use `csv-analyzer` skill for analysis (separate step)

## CRITICAL: Profile Lock Required

**Before ANY query execution, verify profile is locked.**

If no profile locked, respond:
```
Profile lock required. Say "agency_1" or "agency_2" to select profile.
```

## Command Format

```
Get [resource] for [account] [days]d
```

**Examples:**
- `Get search terms for Example Account` → 30 days (default)
- `Get campaigns for Example Account 60d` → 60 days
- `Get keywords for Example Account 90d sort:clicks`

**Defaults:**
- Days: 30
- Sort: cost DESC

## Process

### Step 1: Verify Profile Lock

Check if profile is locked. If not, ask user to lock profile first.

### Step 2: Parse Request

Extract:
1. **Resource** - Short name (see `references/resources.md`)
2. **Account** - Name or alias
3. **Days** - Time period (default 30)

### Step 3: Resolve Account

Read `credentials/[profile]/accounts.json`:
- Match by key, name, or alias (case-insensitive)
- If no match, list similar accounts and ask

### Step 4: Execute Query

```bash
python scripts/query.py \
  --profile [profile] \
  --account [account-key] \
  --resource [resource] \
  --days [days] \
  --output ./data/[profile]/[YYYYMMDD]-[account]-[resource].csv
```

### Step 5: Return Minimal Output

**Only return:**
```
[PROFILE: agency_1]

Query complete.
File: data/google-ads/agency_1/20260109-example-account-search-terms.csv
Rows: 3,847

Say "analyze it" to run insights, or ask another query.
```

**DO NOT:**
- Display raw data in conversation
- Show sample rows
- Auto-analyze (wait for user to request)

## Resources

See `references/resources.md` for resource mappings.

| Short Name | Description | GAQL Template |
|------------|-------------|---------------|
| `search-terms` | Search query report | `search-terms.gaql` |
| `campaigns` | Campaign performance | `campaigns.gaql` |
| `keywords` | Keyword performance | `keywords.gaql` |
| `ad-groups` | Ad group performance | `ad-groups.gaql` |
| `conversions` | Conversion tracking | `conversions.gaql` |
| `budgets` | Budget utilization | `budgets.gaql` |
| `assets` | Asset performance (PMAX) | `assets.gaql` |
| `geo` | Geographic performance | `geo.gaql` |

## File Naming Convention

```
data/google-ads/[profile]/[YYYYMMDD]-[account-slug]-[resource].csv
```

Examples:
- `data/google-ads/agency_1/20260109-example-account-search-terms.csv`
- `data/google-ads/agency_1/20260109-example-campaigns.csv`
- `data/google-ads/agency_2/20260109-example-keywords.csv`

## Error Handling

**Account not found:**
```
Account "example-search" not found.

Similar matches:
- example-account (Example Account) - Portfolio 1

Did you mean example-account?
```

**Query fails:**
- Show error message
- Suggest common fixes (invalid date range, permissions)

## Integration

After query completes, user can:
1. Say "analyze it" → triggers `csv-analyzer` skill
2. Ask for different resource/account
3. Re-query with different date range

## Files

```
.claude/skills/google-ads-query/
├── SKILL.md                    ← This file
├── scripts/
│   └── query.py                ← Unified query→CSV script
└── references/
    ├── resources.md            ← Resource mappings
    └── *.gaql                  ← 8 query templates
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fourteenwm](https://github.com/fourteenwm)
- **Source:** [fourteenwm/ppc-ai-skills](https://github.com/fourteenwm/ppc-ai-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fourteenwm-ppc-ai-skills-google-ads-query
- Seller: https://agentstack.voostack.com/s/fourteenwm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.