# DataForSEO: live SEO data (extension) Human Guide

## What This Is For
Live SEO data via DataForSEO MCP server: SERP analysis, keyword research (volume, difficulty, intent, trends), backlink profiles, on-page analysis, competitor and content analysis. It gives the agent a clearer input/output frame for search and SEO workflows: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the DataForSEO: live SEO data (extension) agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for DataForSEO: live SEO data (extension).
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the DataForSEO: live SEO data (extension) guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- Prefer bulk endpoints over multiple single calls
- Use default parameters (US, English) unless user specifies otherwise
- Cache results mentally within a session; don't re-fetch the same data
- Warn user before running expensive operations (full backlink crawls, large keyword lists)
- If `"status": "approved"` → proceed with the API call
- If `"status": "needs_approval"` → show the cost estimate to the user and ask for confirmation before proceeding
- If `"status": "blocked"` → inform the user that the daily budget limit would be exceeded; do NOT proceed
- `/seo dataforseo costs today` → show today's spending breakdown
- `/seo dataforseo costs summary` → show 7-day spending history
- `/seo dataforseo costs config --mode threshold --threshold 0.50` → configure approval mode
- Domain dominance: which sites own the most image positions (top 10 domains by count)
- Alt text patterns: common title/alt text patterns in top-ranking images

## Decision Points And Nuance
The original skill emphasizes: Prerequisites, API Credit Awareness, Cost Guardrails, Quick Reference, SERP Analysis, `/seo dataforseo serp <keyword>`, `/seo dataforseo serp-youtube <keyword>`, `/seo dataforseo youtube <video_id>`, `/seo dataforseo serp-images <keyword>`, Keyword Research.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- Cache results mentally within a session; don't re-fetch the same data
- If `"status": "blocked"` → inform the user that the daily budget limit would be exceeded; do NOT proceed
- **Parameters:** keyword (required), depth (optional, max 700, billed per 100-result increment), search_param (optional, e.g. "site:example.com")
- **Cost warning:** Using `site:` or `filetype:` operators incurs **5x API cost**. Warn user before running filtered queries.
- Avoid `site:` and `filetype:` operators in image SERP queries (5x cost multiplier)
- Cache session results — don't re-fetch the same keyword/domain within a session

## Copy-And-Paste Prompt
```text
Use the DataForSEO: live SEO data (extension) human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the agricidaniel/claude-seo skill entry for `seo-dataforseo`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# DataForSEO: Live SEO Data (Extension)

Live search data via the DataForSEO MCP server. Provides real-time SERP results
(organic + images), keyword metrics, backlink profiles, on-page analysis, content
analysis, business listings, AI visibility checking, and LLM mention tracking
across 9 API modules with 79+ MCP tools.

## Prerequisites

This skill requires the DataForSEO extension to be installed:
```bash
./extensions/dataforseo/install.sh
```

**Check availability:** Before using any DataForSEO tool, verify the MCP server
is connected by checking if `serp_organic_live_advanced` or any DataForSEO tool
is available. If tools are not available, inform the user the extension is not
installed and provide install instructions.

## API Credit Awareness

DataForSEO charges per API call. Be efficient:
- Prefer bulk endpoints over multiple single calls
- Use default parameters (US, English) unless user specifies otherwise
- Cache results mentally within a session; don't re-fetch the same data
- Warn user before running expensive operations (full backlink crawls, large keyword lists)

## Cost Guardrails

**Before every DataForSEO MCP call**, run cost estimation:
```
claude-seo run dataforseo_costs.py check <endpoint> [--count N]
```

- If `"status": "approved"` → proceed with the API call
- If `"status": "needs_approval"` → show the cost estimate to the user and ask for confirmation before proceeding
- If `"status": "blocked"` → inform the user that the daily budget limit would be exceeded; do NOT proceed

**After each API call completes**, log the cost:
```
claude-seo run dataforseo_costs.py log <endpoint> <actual_cost>
```

**User commands for cost management:**
- `/seo dataforseo costs today` → show today's spending breakdown
- `/seo dataforseo costs summary` → show 7-day spending history
- `/seo dataforseo costs config --mode threshold --threshold 0.50` → configure approval mode

Load `references/cost-tiers.md` for the full pricing table, budget presets, and cost reduction tips.

## Quick Reference

| Command | What it does |
|---------|-------------|
| `/seo dataforseo serp <keyword>` | Google organic SERP results |
| `/seo dataforseo serp-images <keyword>` | Google Images SERP results |
| `/seo dataforseo serp-youtube <keyword>` | YouTube search results |
| `/seo dataforseo youtube <video_id>` | YouTube video deep analysis |
| `/seo dataforseo keywords <seed>` | Keyword ideas and suggestions |
| `/seo dataforseo volume <keywords>` | Search volume for keywords |
| `/seo dataforseo difficulty <keywords>` | Keyword difficulty scores |
| `/seo dataforseo intent <keywords>` | Search intent classification |
| `/seo dataforseo trends <keyword>` | Google Trends data |
| `/seo dataforseo backlinks <domain>` | Full backlink profile |
| `/seo dataforseo competitors <domain>` | Competitor domain analysis |
| `/seo dataforseo ranked <domain>` | Ranked keywords for domain |
| `/seo dataforseo intersection <domains>` | Keyword/backlink overlap |
| `/seo dataforseo traffic <domains>` | Bulk traffic estimation |
| `/seo dataforseo subdomains <domain>` | Subdomains with ranking data |
| `/seo dataforseo top-searches <domain>` | Top queries mentioning domain |
| `/seo dataforseo onpage <url>` | On-page analysis (Lighthouse + parsing) |
| `/seo dataforseo tech <domain>` | Technology stack detection |
| `/seo dataforseo whois <domain>` | WHOIS registration data |
| `/seo dataforseo content <keyword/url>` | Content analysis and trends |
| `/seo dataforseo listings <keyword>` | Business listings search |
| `/seo dataforseo ai-scrape <query>` | ChatGPT web scraper for GEO |
| `/seo dataforseo ai-mentions <keyword>` | LLM mention tracking for GEO |

---