tool-dataforseo

Tool: DataForSEO

Thin wrapper for the DataForSEO API — SERP results and keyword data. Other skills call this instead of re-describing the API.

Requirements

• curl
• jq
• .env credentials listed below

Auth

.env:

DATAFORSEO_LOGIN=
DATAFORSEO_PASSWORD=

HTTP Basic auth (login:password). Base: https://api.dataforseo.com/v3. Request bodies are an array of task objects.

Endpoints

Action	Endpoint	Use
SERP	POST /serp/google/organic/live/advanced	Top organic results for a phrase
Keyword volume	POST /keywords_data/google_ads/search_volume/live	Search volume / CPC / competition
LLM response	POST /ai_optimization/{engine}/llm_responses/live	Answer-engine response + cited sources
LLM models	POST /ai_optimization/{engine}/llm_responses/models	Model names the engine currently accepts
Account	POST /appendix/user_data	Check balance / credentials

location_name uses DataForSEO format, e.g. "Poland", "United States".

{engine} is chat_gpt, claude, gemini, or perplexity. The request shape is the same across engines; only some optional parameters differ.

Scripts

# Top 10 organic results for a phrase + country (prints url + title list)
bash .agents/skills/tool-dataforseo/scripts/serp.sh "drupal migration agency" "Poland"

# Keyword search volume (prints JSON)
bash .agents/skills/tool-dataforseo/scripts/keyword.sh "drupal migration" "Poland"

# Answer-engine response + cited sources (prints answer, citations, model, cost)
bash .agents/skills/tool-dataforseo/scripts/llm-response.sh chat_gpt \
  "best drupal migration agency for mid-market retail" PL

# Which models this engine currently accepts — run this first, names drift
bash .agents/skills/tool-dataforseo/scripts/llm-response.sh --models chat_gpt

# Raw JSON passthrough
bash .agents/skills/tool-dataforseo/scripts/llm-response.sh --json perplexity "..." PL

llm-response.sh notes

• web_search is forced on. Without it the answer is not grounded in the live web and returns no citations, which makes the run useless for visibility work.
• Prompts are capped at 500 characters by the API. The script fails on a longer prompt rather than truncating it, because a silently shortened prompt makes runs incomparable across batches.
• Only response items of type message are the answer. Reasoning items are excluded.
• An empty citation list prints none, so "no citations" is distinguishable from a failed extraction.
• Model names change. If a call fails on model_name, run --models and pass one.

Rules

1. Credentials from .env only.
2. Paid API — cache results in workspace/ where possible; don't re-query.
3. For competitor discovery, dedupe by root domain after fetching.
4. Degrade gracefully if unset — calling skills should fall back to AI research.
5. Answer engines are non-deterministic. One LLM response is a sample, not a fact; the calling skill decides how many runs make a finding.

Used by

intel-competitor-discovery (SERP), marketing-seo-research (keywords), marketing-service-page (SERP), intel-ai-visibility (LLM responses).