How to Build an SEO Audit Agent in Claude Code

import requests
from datetime import date

API_KEY = "your-scavio-api-key"
YOUR_DOMAIN = "yoursite.com"

KEYWORDS = [
    "best project management software",
    "project tracker for teams",
    "asana alternative 2026",
    "free task management tool",
    "kanban board online"
]

def audit_keyword(keyword: str) -> dict:
    r = requests.post(
        "https://api.scavio.dev/api/v1/search",
        json={"query": keyword, "include_ai_overview": True, "num_results": 20},
        headers={"x-api-key": API_KEY},
        timeout=20
    )
    r.raise_for_status()
    data = r.json()
    results = data.get("organic_results", [])
    position = next((i + 1 for i, res in enumerate(results) if YOUR_DOMAIN in res.get("link", "")), None)
    ao = data.get("ai_overview")
    aio_cited = bool(ao and any(YOUR_DOMAIN in s.get("link", "") for s in ao.get("sources", [])))
    return {"keyword": keyword, "position": position, "ai_overview": bool(ao), "aio_citation": aio_cited}

def generate_report(keywords: list, domain: str) -> str:
    rows = [audit_keyword(kw) for kw in keywords]
    lines = [f"# SEO Audit: {domain} — {date.today()}\n",
             "| Keyword | Position | AI Overview | AIO Citation |",
             "|---------|----------|-------------|--------------|"]
    not_ranking = [r for r in rows if not r["position"]]
    p2 = [r for r in rows if r["position"] and r["position"] > 10]
    cited = [r for r in rows if r["aio_citation"]]

    for row in rows:
        pos = str(row["position"]) if row["position"] else "not ranking"
        lines.append(f"| {row['keyword']} | {pos} | {'yes' if row['ai_overview'] else 'no'} | {'yes' if row['aio_citation'] else 'no'} |")

    lines.append("\n## Action Plan")
    if not_ranking:
        lines.append(f"- Create or optimize pages for: {', '.join(r['keyword'] for r in not_ranking[:3])}")
    if p2:
        lines.append(f"- Build links to pages targeting: {', '.join(r['keyword'] for r in p2[:3])}")
    if not cited:
        lines.append("- No AI Overview citations detected. Add FAQ schema and expand definition sections.")
    if cited:
        lines.append(f"- Maintain AIO citations for: {', '.join(r['keyword'] for r in cited)}")
    return "\n".join(lines)

if __name__ == "__main__":
    print(generate_report(KEYWORDS, YOUR_DOMAIN))

const API_KEY = 'your-scavio-api-key';
const YOUR_DOMAIN = 'yoursite.com';

async function auditKeyword(keyword) {
  const res = await fetch('https://api.scavio.dev/api/v1/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({ query: keyword, include_ai_overview: true, num_results: 20 })
  });
  const data = await res.json();
  const results = data.organic_results ?? [];
  const position = results.findIndex(r => r.link?.includes(YOUR_DOMAIN)) + 1 || null;
  const ao = data.ai_overview;
  const aioCited = ao ? (ao.sources ?? []).some(s => s.link?.includes(YOUR_DOMAIN)) : false;
  return { keyword, position, aiOverview: !!ao, aioCited };
}

const keywords = ['best project management software', 'asana alternative 2026'];
const rows = await Promise.all(keywords.map(auditKeyword));

console.log('| Keyword | Position | AI Overview | AIO Citation |');
for (const row of rows) {
  console.log(`| ${row.keyword} | ${row.position ?? 'not ranking'} | ${row.aiOverview ? 'yes' : 'no'} | ${row.aioCited ? 'yes' : 'no'} |`);
}

# SEO Audit: yoursite.com - 2026-05-22

| Keyword | Position | AI Overview | AIO Citation |
|---------|----------|-------------|-------------- |
| best project management software | 7 | yes | no |
| project tracker for teams | not ranking | no | no |
| asana alternative 2026 | 14 | yes | yes |
| free task management tool | 3 | yes | no |
| kanban board online | not ranking | yes | no |

## Action Plan
- Create or optimize pages for: project tracker for teams, kanban board online
- Build links to pages targeting: asana alternative 2026
- No AI Overview citations for most keywords. Add FAQ schema and expand definition sections.