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.

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
  1. Start with /search or /analyze/serp to understand the current SERP, features, and likely intent.
  2. If the keyword looks local, branch into /audit/local or /local-visibility/track.
  3. If the page opportunity is editorial, branch into /content/gap for missing topics and a compact content brief.
  4. 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.
  5. 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 guideClaude Desktop guideOpenClaw guide

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
  1. Use /audit/local for one business and one location when you need listing quality and readiness signals.
  2. Use /audit/local/batch when you need to enqueue many local audits at once for agency or cron-driven review queues.
  3. Use /local-visibility/track when you need visibility scores across keywords and locations, rather than listing quality alone.
  4. 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.
  5. 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
  1. Send a target URL and keyword into /content/gap.
  2. Read the returned content_brief, missing_topics, and agent_workflow.
  3. Limit the downstream writing step to the highest-signal gaps instead of rewriting the whole article.
  4. Optionally combine /content-decay/detect with /content/gap so refreshes start only when ranking momentum actually weakens.
  5. Store structured output in your CMS or job system so refresh work is versioned and reviewable.

Recommended Endpoints

  • /content/gap
  • /content-decay/detect
  • /extract

What You Get Back

  • •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 guideMake 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
  1. Use /analyze/serp to understand the overall SERP shape and whether local or other high-impact features dominate.
  2. Use /ai-overview/extract when you need direct AI Overview detection and candidate citation sampling.
  3. 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.
  4. 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
  1. Use /rank/track to enqueue a rank check for a keyword and a specific target URL.
  2. Poll /jobs/{id} or stream /jobs/{id}/events while the job completes.
  3. Use GET /rank/track for historical rank context after repeated checks.
  4. When a page drops or stalls, branch into /content/gap or /analyze/serp instead of guessing why performance changed.
  5. 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 guiden8n 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
  1. Start with /search when you want raw results, domain filtering, or quick SERP evidence.
  2. Use /analyze/serp when you need intent, competition level, dominant SERP features, and recommended content format.
  3. If the opportunity looks real, route the chosen landing page or article through /content/gap to scope the content work.
  4. 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
  1. Use /social/listen to collect web discussion evidence around a product category, pain point, or audience phrase.
  2. Use /keyword-cluster/build to turn large keyword lists into intent-led groupings and likely page targets.
  3. Use /llm-mentions/track to test whether a brand appears in prompt-set discovery surfaces across repeated queries.
  4. Feed the highest-signal clusters into /analyze/serp or /content/gap for deeper planning.

Recommended Endpoints

  • /social/listen
  • /keyword-cluster/build
  • /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
  1. Register a webhook endpoint with /webhooks/endpoints.
  2. Queue async jobs from any workflow endpoint you use in production.
  3. Receive job.completed or job.failed events and write them into your own queue, CRM, or reporting system.
  4. Inspect /webhooks/deliveries for failures and retry a delivery without rerunning the underlying SEO job.
  5. 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 guideMake 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 ReferenceSDKs & LibrariesQuickstart