Documentation

Use Cases

AgentSEO is not a dashboard-first SEO suite. It is a search intelligence layer for builders who want strict outputs, async jobs, and workflows an agent can actually use. This page shows the highest value ways to wire the API into real systems.

The current live page was too narrow and one of the local SEO examples blurred local audit with visibility tracking. This version is aligned with the current production workflow surface.

Need the workflow chain?

Start with workflow bundles when you need the exact sequence of APIs for launch, refresh, AI visibility, programmatic SEO, or competitor-gap work.

Need the runtime model first?

Start with the SEO agent guide if you need a safer model for collection, decision, and action before choosing a use case.

Need the measurement layer?

Start with the AI visibility guide if the workflow depends on prompt sets, citations, and reporting discipline.

Need the GEO framework?

Start with the GEO guide when the use case is really about answer-layer visibility, AI Overviews, or Google AI Mode follow-up.

Claude Code prompt: opportunity to refresh loop

Use AgentSEO to find the best SEO refresh opportunity for my site.

1. Call /opportunities/find for my domain with keyword_limit=25.
2. Pick the highest-priority existing-page opportunity.
3. Call /opportunities/brief for that keyword/page.
4. If the page already exists, call /content/refresh-brief for the URL and keyword.
5. Return a human-reviewable edit plan with sections to add, internal links, schema, validation checklist, and what to track after publishing.
6. Do not publish automatically. After edits ship, call /rank/track for the keyword/page.

Customers only see AgentSEO workflow outputs such as agent_workflow, refresh_brief, implementation_brief, and markdown_summary. Provider internals are not part of the public API contract.

Start Narrow, Then Branch

Most reliable workflows start with one diagnostic endpoint such as /search, /analyze/serp, /audit/local, or /content/gap, then branch only when the result justifies the next call.

Prefer Async for Real Work

Use sync windows for demos and short checks. For production agents, assume queued jobs, poll_url, events_url, and webhook delivery are the normal path.

Use Deterministic Geo Inputs

When you care about repeatability across locations, pass location_code so the same request resolves the same way every time.

Consume the Agent Layer, Not Just Raw Output

The highest-value part of the response is usually agent_workflow, serp_opportunity, or agent_support because those blocks compress what to do next.

Agent SEO Copilots

Give an autonomous agent a reliable search-intelligence loop instead of forcing it to scrape pages and guess what to do next.

Best Fit

Builders using MCP, custom agents, LangChain, OpenClaw, n8n, or internal workflow runners.

Primary Goal

Turn vague requests like “find the best page to improve next” into deterministic, tool-driven decisions.

Workflow

Start with /search or /analyze/serp to understand the current SERP, features, and likely intent.
If the keyword looks local, branch into /audit/local or /local-visibility/track.
If the page opportunity is editorial, branch into /content/gap for missing topics and a compact content brief.
If the query triggers AI surfaces, branch into /ai-overview/extract to inspect whether AI Overview is present and what domains appear in the sampled candidate set.
Use /jobs/{id} or /jobs/{id}/events to let the agent wait on long-running work without losing state.

Recommended Endpoints

/search
/analyze/serp
/content/gap
/ai-overview/extract
/jobs/{id}
/jobs/{id}/events

What You Get Back

•serp_opportunity or agent_support to help the agent pick the next branch
•agent_workflow with decision, evidence, recommended actions, and next_calls
•pollable job status for long-running steps

Related runtime guides

Claude Code guide Claude Desktop guide OpenClaw guide

Builder-Marketer Workflows with Claude Code

Use Claude Code as a working surface for SEO loops, then rely on AgentSEO for the grounded state and docs for the repeatable handoff.

Best Fit

Hybrid builder-marketers and technical marketers who can move across prompts, workflow logic, and lightweight internal tooling.

Primary Goal

Turn repeated SEO questions into tool-backed loops, small internal tools, or monitored workflows without waiting on a full product team.

Workflow

Start in Claude Code with one repeated operator question such as SERP triage, content-gap scoping, or prompt-set review.
Connect AgentSEO over MCP so Claude can inspect real workflow state instead of inferring everything from pasted context.
Keep the first loop narrow: inspect, branch, summarize, and return a next action instead of trying to publish automatically.
If the same question keeps repeating, wrap the loop in a small internal tool or promote it into a monitored workflow with review gates.
Document the setup, boundaries, and manual review points so the workflow becomes reusable instead of staying trapped in one prompt thread.

Recommended Endpoints

/analyze/serp
/content/gap
/audit/local
/jobs/{id}
/jobs/{id}/events

What You Get Back

•decision-shaped workflow results a marketer can inspect without reading raw API payloads
•branch-ready tool outputs for Claude Code or a lightweight internal interface
•a cleaner path from one useful prompt into a repeatable system

Vibe Marketer Opportunity Finder

Start with a domain and let AgentSEO turn ranked keywords into prioritized SEO actions before you burn credits on deeper page analysis.

Best Fit

Founder-marketers, PMMs, solo SEO operators, and agent builders who want the next best SEO move without reading raw keyword exports.

Primary Goal

Find quick wins, AI Overview opportunities, commercial pages to refresh, lost rankings, and competitor gaps from one agent-ready API call.

Workflow

Call /opportunities/find with a target domain or URL and a small keyword_limit for the first pass.
Use the returned opportunity score, priority, evidence, and markdown_summary to choose the few opportunities worth deeper work.
Call /keyword-ideas/suggest when you need to expand a seed topic into long-tail ideas before clustering or mapping pages.
Call /keyword-metrics/overview when you already have a keyword list and need search metrics, priority scores, and page-type guidance.
Call /domain/traffic-estimate when you have a shortlist of competitor or market domains and need to choose which ones deserve deeper analysis credits.
Call /backlinks/summary when you need authority, spam-risk, and broken-link signals before deciding whether rankings are limited by links or content.
Call /backlinks/new-lost-timeseries when you need to know whether link authority is growing, leaking, volatile, or stable over time.
Call /backlinks/page-intersection when you need exact source pages linking to competitors but not to your domain before outreach.
Call /backlinks/opportunity-finder when backlink prospects or link-gap exports need to become a safe prioritized outreach, reclaim, repair, and digital PR plan.
Call /backlinks/competitors when you need backlink-profile competitors for link-gap research, not just keyword/SERP competitors.
Call /backlinks/domain-pages when you need to find backlink-bearing pages worth protecting, repairing, reclaiming, refreshing, or repeating as linkable assets.
Call /backlinks/referring-domains when you need to decide which linking domains are worth protecting, reclaiming, repairing, reviewing, or repeating.
Call /backlinks/anchors when you need to understand whether backlink text is branded, generic, commercial, risky, broken, or useful for content positioning.
Call /backlinks/list after the summary when you need actual source URLs to protect, reclaim, repair, review, or use as outreach references.
Call /domain/competitors when you need to identify which search competitors deserve deeper keyword and page-level analysis.
Call /domain/intersection after choosing a competitor to compare shared keyword deficits, current advantages, or target1-exclusive keywords.
Call /pages/intersection when you need exact page-level keyword gaps between competitor URL groups and your own excluded pages.
Call /content/competitor-gap-matrix when competitor page or keyword exports need to become a page-type and buyer-stage content plan.
Call /domain/ranked-keywords when you want the current ranked keyword inventory for a domain, subdomain, or page URL before choosing refresh targets.
Call /domain/relevant-pages when you need to choose which URLs are winners, decliners, growth candidates, or recovery targets before spending more credits.
Call /opportunities/brief for the selected keyword/page when you want an implementation plan instead of another raw SEO report.
Call /content/serp-outline when the next move is creating a new page instead of refreshing an existing URL.
Call /content/keyword-map before drafting to assign one primary URL per keyword intent and catch missing pages or cannibalization risk.
Call /content/cannibalization when multiple existing URLs appear to target the same query and you need a safe fix plan before redirecting, canonicalizing, or rewriting.
Call /content/brief when a writer or coding agent needs the fuller production brief: audience, meta, proof requirements, conversion plan, and QA checklist.
Call /content/draft-qa after a human or agent drafts the page to catch missing SERP expectations, weak sections, and proof gaps before publishing.
Call /content/title-meta to prepare search title and meta description options that match the visible page promise.
Call /content/technical-qa as the final pre-publish gate for metadata, indexability, canonicals, headings, schema, internal links, and image-alt checks.
Call /content/action-plan to turn selected opportunities, refreshes, QA fixes, and link work into a capacity-aware 30-day execution calendar.
Call /site/sitemap-audit before content expansion or after site changes to find important URLs missing from sitemaps, sitemap-only orphan candidates, and internal-link gaps.
Call /serp/volatility when rank-tracker snapshots show movement and you need to know whether the whole SERP changed before editing pages.
Call /page/cro-qa before shipping SEO landing pages to check whether the page can turn organic traffic into trials, demos, purchases, or leads.
Call /ai-visibility/prompt-set to build a stable AI visibility monitoring set mapped to platforms, competitors, citations, and owned assets before tracking answer-layer movement.
Call /content/programmatic-template before building pages at scale so weak templates, missing unique fields, indexation risk, and internal-link requirements are caught before publishing.
Call /content/schema-plan before publishing to generate JSON-LD guidance, required fields, and validation steps without spending provider credits.
Call /content/internal-links before publishing to choose relevant target pages, natural anchors, and crawlable link placements.
For an existing page, call /content/refresh-brief to turn the selected opportunity into a writer- or Claude Code-ready refresh plan.
Enable include_serp_competitors or include_competitor_discovery when you need competitive context and are comfortable spending the extra credits.
Only then call the recommended next_api_calls such as /extract, /content/gap, /ai-overview/extract, or /analyze/serp for deeper evidence.
Track the chosen keyword/page with /rank/track after publishing changes so the loop measures outcome, not just recommendations.

Recommended Endpoints

/opportunities/find
/keyword-ideas/suggest
/keyword-metrics/overview
/domain/traffic-estimate
/backlinks/summary
/backlinks/new-lost-timeseries
/backlinks/page-intersection
/backlinks/opportunity-finder
/backlinks/competitors
/backlinks/domain-pages
/backlinks/referring-domains
/backlinks/anchors
/backlinks/list
/domain/competitors
/domain/intersection
/pages/intersection
/content/competitor-gap-matrix
/domain/ranked-keywords
/domain/relevant-pages
/opportunities/brief
/content/serp-outline
/content/keyword-map
/content/cannibalization
/content/brief
/content/draft-qa
/content/title-meta
/content/technical-qa
/content/action-plan
/site/sitemap-audit
/serp/volatility
/page/cro-qa
/ai-visibility/prompt-set
/content/programmatic-template
/content/schema-plan
/content/internal-links
/content/refresh-brief
/extract
/content/gap
/analyze/serp
/rank/track

What You Get Back

•prioritized opportunities with score, type, reason, and evidence
•implementation_brief with sections, on-page changes, schema recommendations, and validation steps
•SERP outline with title options, sections, questions, internal links, and validation checks
•content_brief with audience, SERP expectations, competitor patterns, differentiators, proof requirements, and QA checklist
•draft_qa with publish readiness, missing expectations, proof gaps, editor tasks, and agent_workflow
•schema_plan with recommended schema types, JSON-LD draft, required field checklist, and validation plan
•refresh_brief with title/H1 guidance, sections to add, internal links, schema, and QA checklist
•sitemap_audit with sitemap coverage, orphan candidates, canonical/indexability cleanup, and internal-link fixes
•serp_volatility with rank churn, feature churn, winners, losers, target visibility, and a monitor vs act decision
•page_cro_qa with CTA, proof, objection, friction, and conversion-readiness findings
•ai_visibility_prompt_set with prompt buckets, platform groups, asset mapping, measurement fields, citation checks, and action routing
•programmatic_template_plan with readiness score, scale risk, template sections, indexation gates, internal-link architecture, schema recommendations, and launch QA
•recommended_actions and next_api_calls for downstream agents
•competitor_summary when enrichment is enabled

Local SEO and AEO Operations

Run repeatable local listing audits and visibility checks across locations without turning local search into manual analyst work.

Best Fit

Local SEO agencies, multi-location operators, and technical marketers managing repeated local checks.

Primary Goal

Find weak local entities, weak query-location pairs, and the next highest-leverage local fix.

Workflow

Use /audit/local for one business and one location when you need listing quality and readiness signals.
Use /audit/local/batch when you need to enqueue many local audits at once for agency or cron-driven review queues.
Use /local-visibility/track when you need visibility scores across keywords and locations, rather than listing quality alone.
If visibility is weak, send the worst query-location pairs into /rank/track or /content/gap depending on whether the problem looks like ranking loss or landing-page weakness.
Route completions into a webhook endpoint so downstream systems can create tickets, alerts, or summaries automatically.

Recommended Endpoints

/audit/local
/audit/local/batch
/local-visibility/track
/rank/track
/webhooks/endpoints

What You Get Back

•AEO readiness score and agent brief for listing quality
•overall_visibility_score and weak snapshots for local rankings
•async jobs for large or scheduled local workloads

Content Refresh and Content Gap Automation

Build a content-refresh pipeline that compares your page against the live SERP and tells a writer or agent what to cover next.

Best Fit

Teams maintaining content libraries, programmatic SEO systems, or editorial agents.

Primary Goal

Decide what to update on a page before you spend tokens generating copy or assigning a writer.

Workflow

Send a target URL and keyword into /content/refresh-brief when you want an implementation-ready refresh plan.
Use /content/serp-outline when you are creating a new page and need a SERP-informed outline before drafting.
Use /keyword-ideas/suggest when a seed topic needs more long-tail options before clustering or briefing.
Use /keyword-metrics/overview when a supplied keyword list needs prioritization before page assignment.
Use /domain/ranked-keywords when the refresh source is an existing domain or URL with search traction.
Use /domain/relevant-pages when you need page-level winners, decliners, growth candidates, and recovery targets before choosing URLs to refresh.
Use /content/keyword-map when you need to decide whether a keyword should refresh an existing URL or become a new page.
Use /content/cannibalization when two or more existing pages are sharing queries, impressions, or target keywords and need URL ownership decisions.
Use /content/brief when you need a fuller writer-ready brief with metadata, proof requirements, conversion guidance, and QA checks.
Use /content/draft-qa when a draft exists and you need a pre-publish QA score plus exact editor tasks.
Use /content/title-meta to prepare title and meta description options before pushing the page live.
Use /content/technical-qa to block accidental noindex, canonical, metadata, heading, schema, and internal-link issues before pushing the page live.
Use /content/action-plan when multiple refreshes, QA fixes, and new pages need to become a realistic weekly execution plan.
Use /site/sitemap-audit to confirm important URLs are represented in the sitemap and reachable through internal links before expanding the content set.
Use /serp/volatility when rankings move across multiple snapshots and you need to decide whether to monitor, refresh, or investigate a wider SERP shift.
Use /page/cro-qa after the draft is useful for searchers but before publishing, so CTA and proof gaps do not waste organic traffic.
Use /content/programmatic-template when the refresh or gap project is becoming a repeatable page set and you need safe template, data, indexation, and internal-link rules.
Use /content/schema-plan to prepare structured data and validation steps before pushing the page live.
Use /content/internal-links to add crawlable links from the refreshed page to supplied related pages.
Read the returned refresh_brief, content_gap evidence, markdown_summary, and agent_workflow.
Limit the downstream writing step to the highest-signal gaps instead of rewriting the whole article.
Use /content/gap directly when you only need the lower-level topic comparison.
Optionally combine /content-decay/detect with /content/gap so refreshes start only when ranking momentum actually weakens.
Store structured output in your CMS or job system so refresh work is versioned and reviewable.

Recommended Endpoints

/content/refresh-brief
/content/serp-outline
/keyword-ideas/suggest
/keyword-metrics/overview
/domain/ranked-keywords
/domain/relevant-pages
/content/keyword-map
/content/cannibalization
/content/brief
/content/draft-qa
/content/title-meta
/content/technical-qa
/content/action-plan
/site/sitemap-audit
/serp/volatility
/page/cro-qa
/content/programmatic-template
/content/schema-plan
/content/internal-links
/content/gap
/content-decay/detect
/extract

What You Get Back

•refresh_brief with section, internal link, schema, and validation tasks
•SERP-informed outline with title options, H2s, FAQs, schema, and validation checklist
•content_brief with draft instructions, SERP expectations, proof requirements, and conversion plan
•draft_qa with publish readiness score, weak sections, missing expectations, and editor tasks
•schema_plan with JSON-LD, required fields, missing evidence, and validation checklist
•missing_topics and common_themes from current competitors
•content_brief with suggested title, H1, page type, and must-cover items
•a concise act_now vs monitor decision for refresh triage

Related runtime guides

n8n guide Make guide

AI Overview and Generative Search Monitoring

Check whether AI Overview is appearing for a query and decide whether your next move is citation research, local improvement, or content work.

Best Fit

Teams measuring early GEO visibility and deciding where to focus limited optimization time.

Primary Goal

Detect when a query has moved into an AI-mediated surface and route that query into the right follow-up workflow.

Workflow

Use /analyze/serp to understand the overall SERP shape and whether local or other high-impact features dominate.
Use /ai-overview/extract when you need direct AI Overview detection and candidate citation sampling.
If a target domain is missing from the sampled candidate set, move into /content/gap or /audit/local depending on whether the problem is editorial or local.
Track high-value keywords repeatedly so changes in AI Overview behavior can trigger follow-up work automatically.

Recommended Endpoints

/analyze/serp
/ai-overview/extract
/content/gap
/audit/local

What You Get Back

•ai_overview_detected and overview_status
•sampled candidate evidence for target-domain checks
•agent_workflow recommendations for the next branch

Rank and Visibility Monitoring

Track whether an optimization actually changed rankings, then feed that result back into your planning loop.

Best Fit

Agencies, growth engineers, and product teams who need evidence instead of guesswork after a content or local change.

Primary Goal

Close the loop between an SEO action and the observed rank or visibility outcome.

Workflow

Use /rank/track to enqueue a rank check for a keyword and a specific target URL.
Poll /jobs/{id} or stream /jobs/{id}/events while the job completes.
Use GET /rank/track for historical rank context after repeated checks.
When a page drops or stalls, branch into /content/gap or /analyze/serp instead of guessing why performance changed.
For local entities, combine /rank/track with /local-visibility/track so you measure both page-level and local-pack reality.

Recommended Endpoints

/rank/track
/jobs/{id}
/jobs/{id}/events
/content/gap
/local-visibility/track

What You Get Back

•job-driven rank checks for repeatable monitoring
•rank history plus agent_workflow interpretation
•clear branch points for deeper diagnosis

Related runtime guides

Make guide n8n guide

Competitive Research and Opportunity Mapping

Use live SERP evidence to decide whether a keyword is worth attacking, what kind of page should exist, and where competitors currently win.

Best Fit

Builders planning new pages, agencies scoping campaigns, and technical marketers evaluating keyword opportunities.

Primary Goal

Move from “interesting keyword” to a concrete action plan with page-type and competition context.

Workflow

Start with /search when you want raw results, domain filtering, or quick SERP evidence.
Use /analyze/serp when you need intent, competition level, dominant SERP features, and recommended content format.
If the opportunity looks real, route the chosen landing page or article through /content/gap to scope the content work.
If the opportunity is local, route the same keyword through /audit/local or /local-visibility/track.

Recommended Endpoints

/search
/analyze/serp
/content/gap
/audit/local

What You Get Back

•top domains and top results for quick competitive context
•recommended page type and likely intent
•more reliable go/no-go decisions before content production

Demand Research and Topic Discovery

Collect discussion evidence, weak demand signals, and query clusters that can feed content planning or product messaging work.

Best Fit

Founders, PMMs, technical marketers, and agents gathering demand signals before writing or building.

Primary Goal

Find what people are actually asking, discussing, or clustering around before you publish.

Workflow

Use /social/listen to collect web discussion evidence around a product category, pain point, or audience phrase.
Use /keyword-cluster/build to turn large keyword lists into intent-led groupings and likely page targets.
Use /keyword-ideas/suggest first when you only have a seed topic and need fresh keyword candidates with metrics.
Use /keyword-metrics/overview first when you already have keywords but need volume, difficulty, and prioritization.
Use /domain/ranked-keywords first when the source of truth is an existing domain, competitor, or page URL.
Use /llm-mentions/track to test whether a brand appears in prompt-set discovery surfaces across repeated queries.
Feed the highest-signal clusters into /analyze/serp or /content/gap for deeper planning.

Recommended Endpoints

/social/listen
/keyword-cluster/build
/keyword-ideas/suggest
/keyword-metrics/overview
/domain/ranked-keywords
/llm-mentions/track
/analyze/serp

What You Get Back

•discussion evidence and agent_workflow summaries
•intent-led keyword clusters instead of flat keyword dumps
•prompt-set mention audits for brand visibility experiments

Webhook-Driven Agency and Platform Workflows

Connect AgentSEO to your own systems so long-running jobs create tickets, alerts, summaries, or follow-up jobs automatically.

Best Fit

Teams running cron jobs, internal dashboards, client reporting systems, or multi-step automations.

Primary Goal

Stop polling by hand and let async completions trigger the next system action.

Workflow

Register a webhook endpoint with /webhooks/endpoints.
Queue async jobs from any workflow endpoint you use in production.
Receive job.completed or job.failed events and write them into your own queue, CRM, or reporting system.
Inspect /webhooks/deliveries for failures and retry a delivery without rerunning the underlying SEO job.
Keep /jobs/{id} available as a fallback for systems that still want direct polling.

Recommended Endpoints

/webhooks/endpoints
/webhooks/deliveries
/webhooks/deliveries/{id}/retry
/jobs/{id}

What You Get Back

•workspace-scoped webhook endpoint management
•delivery history and retry support
•cleaner orchestration for high-volume async systems

Related runtime guides

n8n guide Make guide

Common System Patterns

Scheduled Refresh Loop

Nightly or weekly jobs enqueue local audits, content gap checks, content decay scans, or visibility tracking, then send completed results into your own task system.

Agent Branching Loop

One agent calls a diagnostic endpoint first, reads the returned decision block, then branches into the next best workflow instead of calling every endpoint blindly.

Webhook Completion Loop

Long-running jobs finish asynchronously, your system receives a completion event, and only then creates tickets, summaries, or follow-up agent tasks.

Build from real examples

If you are integrating AgentSEO into a production agent or workflow system, use the API reference for exact payloads and the SDKs page for package-level integration details.

API Reference SDKs & Libraries Quickstart