If you want a competitor analysis tool API that an AI coding agent can call on its own, seogeoaeo.ai exposes its whole catalog over MCP and REST on every plan. The agent picks a tool, sees the credit price, runs it once and gets structured findings back. This guide covers setup, the competitor tools worth wiring in, and how to keep an agent from spending more than you meant.
Why an API instead of a dashboard #
Competitor research is repetitive. You look up the same few rivals every month, paste numbers into a doc, and compare. An agent can do the lookups, keep the inputs consistent, and write the comparison. What it needs is a tool surface with clear inputs and predictable cost, and a per-run model gives you that: one call, one price, no session to keep alive.
Connect it #
Create an API key at seogeoaeo.ai/api-keys. Keys start with sga_, are shown once, and spend the workspace's credits.
For Claude Code, add the MCP server:
claude mcp add --transport http --scope user seogeoaeo https://seogeoaeo.ai/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
Cursor, Windsurf and other clients that read an mcpServers file take the same URL and header. The endpoint is Streamable HTTP, stateless, POST only.
Prefer plain HTTP? Each tool is a REST path:
curl -X POST https://seogeoaeo.ai/api/v1/tools/domain-overview/runs \
-H "Authorization: Bearer $SEOGEOAEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"url":"https://www.example.com","market":"us"}}'
Agent runs cost the same credits as runs from the browser.
The competitor tools and their inputs #
| Tool slug | Input | Returns | Credits |
|---|---|---|---|
competitor-finder |
url, market | Sites sharing your Google keywords, close vs general | 38 |
domain-overview |
url, market | Keyword count, est. visits, ad value, links, link rank | 50 |
competitor-keywords |
url, market | Rival's ranking keywords with volume, difficulty, CPC | 35 |
keyword-gap |
url, competitor, market | Rival's top-20 keywords where you are absent | 85 |
backlink-finder |
url | 100 strongest linking sites, 50 link texts | 70 |
competitor-google-ads |
url, market | Ad count, formats, durations, top text ad copy | 15 |
meta-ad-finder |
query, mode, market | Up to 30 active Facebook and Instagram ads | 5 |
linkedin-ad-finder |
company, market | Up to 24 recent LinkedIn ads | 5 |
ai-citation-finder |
query, mode, platform, market | Pages AI Overviews and ChatGPT cite | 160 |
Market codes are two-letter values such as us, gb, de or jp. The ad tools also accept all.
Keep the bill predictable #
Three controls matter when an agent holds the key.
- maxCredits. Pass it with a run and the API refuses any run above that price, returning
max_credits_exceeded(HTTP 402) instead of charging. - Refunds on failure. A run that ends in a 502 (input could not be processed) or 503 (a data provider is down) is refunded. Retry on 503 with backoff and on 429 using the Retry-After header.
- Know which empty results still cost. Competitor Finder and AI Citation Finder charge when the provider finds the domain or topic but no matches, because the lookup itself is billed. Domain Overview refunds a run that finds neither search nor link data.
A monthly job you can hand to an agent #
A simple prompt works: "For each domain in rivals.txt, run domain-overview and competitor-google-ads in the us market with maxCredits 60, then write a table comparing estimated visits, link rank and number of active ads with last month's file." For five rivals that is 325 credits a month, well inside the 2,000 on the $29 Indie plan.
Add keyword-gap against your own site once a quarter to refresh the content backlog.
Limits to tell your agent about #
Every traffic, keyword and link number is an estimate from a data provider, so instruct the agent to compare rivals rather than quote figures as fact. The keyword tools cover the whole domain, not one folder. Nothing here reports a rival's bid keywords or ad spend outside Google's own estimate in Domain Overview. And there is no rank tracker; if your pipeline needs daily positions, pair this with a suite that tracks rankings.
Start small #
Run one tool by hand in the browser first, read the output shape, then give the agent the slug. The full tool reference lists every input and limit in one plain-text file your agent can read directly.