API & MCP

Use Seotrends from your own scripts over a JSON API, or let an AI assistant use it for you through our MCP server. Both are included with the Business and Agency plans and work exactly like the dashboard: the same plan limits, and the same monthly searches, reports and credits. Whatever you spend through the API is gone from the dashboard too, and the other way round.

Authentication

Create your key in Account → API and MCP server. It is shown once: we only keep a fingerprint of it, so copy it somewhere safe. If you lose it, generate a new one (the old one stops working at once). Send it with every request:

curl https://seotrends.pro/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

An X-Api-Key: YOUR_API_KEY header works too. The base URL is https://seotrends.pro/v1. Reads use GET with query parameters; actions use POST (or PATCH) with a JSON body. Every response is JSON.

Access follows your subscription in real time: if a renewal payment fails or a cancellation ends, the key stops working with 402 or 403 until the plan is active again.

What costs what

Exactly the same as in the dashboard. Reading what you already have is always free.

Action	Spends	Free when…
POST /keyword-research	1 Keyword Research search	you already searched that keyword and market this month
POST /site-explorer	1 Site Explorer lookup	you already opened that domain
POST /backlinks	1 backlink check, charged when the report is ready	you already opened that report, or it failed
POST /competitor-reports	1 competitor report of the month	the same report (same domains and market) already exists
POST /goldmines/unlock	1 SEO Goldmines credit per locked site	the site is already visible (above your plan's free DR, already unlocked, or the free site of the month)
AI prompts, tracked keywords, projects	Room in your plan's limits	within your limits
Scans	Follow your plan's scan frequency	-

Responses to actions that spend include a spent object and the quota left. Calls from the same account are queued while they spend, so ten requests at once can never use more than you have left.

On top of your plan, the API has request limits to protect the service:

Plan	Requests / minute	Requests / day	Goldmines listing rows / day
Business	60	5,000	25,000
Agency	120	10,000	100,000

Daily counters reset at midnight server time (Europe/Madrid).

Account

Endpoint	Returns
GET /me	Your plan, the quotas left this month (Keyword Research, Site Explorer, backlink checks, competitor reports), your Goldmines credits, your plan's limits and today's API usage.
GET /countries	Market codes the endpoints accept (US, ES, UK…).
GET /categories	Category ids for the Goldmines filters.

Projects

A project is one of your domains, with its market, competitors, AI prompts and tracked keywords. Most tools hang off it. As in the dashboard, the research tools stay locked while you have projects but none with its setup finished (409 setup_incomplete).

Endpoint	What it does
GET /projects	Your projects and whether each setup is finished.
GET /projects/{domain}	One project: market, competitors, latest AI and SEO visibility, monthly traffic (finished months).
POST /projects	Create a project with its whole setup in one call. Uses one of your plan's project slots.

curl https://seotrends.pro/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "country": "US",
    "language": "en",
    "topic": "Running shoes",
    "competitors": ["rival-one.com", "rival-two.com"],
    "prompts": ["best running shoes for beginners", "where to buy trail shoes online"],
    "keywords": ["running shoes", "trail running shoes"]
  }'

It runs the same steps as the setup in the dashboard: the plan limits apply (anything over them is reported in not_saved_over_plan_limit), and the first AI and SEO scans and the free setup competitor report start in the background. Your email must be confirmed.

AI Visibility

Endpoint	What it does
GET /projects/{domain}/ai-visibility	Index, share and mentions per AI engine for you and your competitors over time, and every prompt with its latest result per engine.
POST /projects/{domain}/ai-visibility/prompts	{"prompts": ["…", "…"]}. Adds prompts up to your plan's limit per project, skipping the ones you already have. New prompts are scanned right away, within what your plan scans per cycle.
PATCH /projects/{domain}/ai-visibility/prompts/{prompt_id}	{"prompt": "new text"}. A prompt that was already measured is archived with its results and the new text starts clean.
POST /projects/{domain}/ai-visibility/scan	Runs the full scan now. Allowed once per your plan's scan interval; earlier calls get 429 too_soon with the next date.

SEO Visibility

Endpoint	What it does
GET /projects/{domain}/seo-visibility	Your visibility index against your competitors over time, and every tracked keyword with its latest position and URL.
POST /projects/{domain}/seo-visibility/keywords	{"keywords": ["…"], "country": "US"}. Adds keywords up to your plan's limit per project and measures them.
POST /projects/{domain}/seo-visibility/scan	Measures the tracked keywords now.

Competitor reports

Endpoint	What it does
GET /competitor-reports	Your reports, the ones being built and this month's report quota.
GET /competitor-reports/{id}	One report: monthly visits, countries, traffic sources, engagement, keywords and top keywords for every domain. While it is being built: "status": "running".
POST /competitor-reports	{"domain": "example.com", "competitors": ["…"], "country": "US"}. Orders a report (a few minutes). Counts against the month's reports and the daily cap of 5; adds the domain to your projects if it is not there yet.

Keyword Research

curl https://seotrends.pro/v1/keyword-research \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"keyword": "running shoes", "country": "US"}'

Returns the keyword's volume, difficulty and CPC, up to 500 related ideas with their metrics, and the pages that rank for it. charged tells you whether this call used a search.

Site Explorer

curl https://seotrends.pro/v1/site-explorer \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "country": "US"}'

Overview of any domain: DR, keywords, traffic and its value, engagement, traffic sources, traffic per country, the top 50 keywords in a market and monthly traffic. A domain we do not have yet comes back as "status": "fetching": call again in a minute (it is not charged twice).

Backlink Checker

Endpoint	What it does
POST /backlinks	{"target": "example.com", "mode": "domain"} (domain, exact or url). Starts or reopens a report and returns its id.
GET /backlinks/{id}	Status, then the summary (DR, backlinks, referring domains, dofollow share), the links 100 per page (links_page) and the top referring domains.

SEO Goldmines

The domain database. Sites above your plan's free DR (45) are open; the rest come back "locked": true with their metrics but without their name, exactly like the dashboard. Unlock them with your credits.

Endpoint	What it does
GET /goldmines/domains	Search (the first 10,000 matches; meta.more_than_10000 tells you to narrow the filters). Filters: countries, categories, dr_min, dr_max, age_min, age_max, traffic_min, value_min, keywords_min, top3_min, cpc_min, paid_min, paid_max (paid search: % of the clicks on its keywords that go to ads, 0-100), growth_min, quality_min, adult (exclude/include/only), only_unlocked. Sort: sort (traffic_value, growth_score, opportunity, quality_score, keywords, volume, age, top3, avg_position, traffic, dr) and order. Paging: page, per_page (max 100, first 10,000 rows).
GET /goldmines/domains/{domain}	One open site with its keywords (country, page, per_page) and monthly traffic. A locked site answers 402 locked with its id.
POST /goldmines/unlock	{"ids": [123, 456]} (up to 200). Unlocks them for good and returns their names and top keywords. All or nothing: with too few credits nothing is unlocked or charged.

Errors

Errors come with a stable error code and a readable message:

Status	Code	Meaning
401	missing_credentials, invalid_key	No key, or a key that does not exist (revoked or regenerated).
402	payment_required	The last renewal failed. Update your card and access resumes by itself.
402	insufficient_credits, locked	Not enough Goldmines credits, or the site has to be unlocked first.
403	plan_required	Your plan does not include the API or that tool.
403	quota_exhausted, project_limit	You used what your plan includes this month, or all your project slots.
404	project_not_found, report_not_found, not_found	Not on this account.
409	setup_incomplete	Finish a project's setup first.
409	busy	Another spending call from your account is running. Retry in a few seconds.
429	rate_limited, daily_cap, too_soon	A request limit, the daily report cap, or a scan before your plan's interval.
400	invalid_parameter	Fix the parameter; the message says how.

MCP server

MCP lets an AI assistant use Seotrends directly, so you can ask in plain language instead of writing requests. It uses the same key, the same plan limits and the same credits. Tools that spend say so in their description, and assistants usually ask you before using them.

Claude Code

claude mcp add --transport http seotrends https://seotrends.pro/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop, Cursor and other clients

Add this to the MCP configuration file:

{
  "mcpServers": {
    "seotrends": {
      "type": "http",
      "url": "https://seotrends.pro/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

The tools:

Tool	What it does
get_account	Plan, quotas left, credits and limits.
list_projects, get_project, create_project	Your projects; create one with its full setup.
get_ai_visibility, add_ai_prompts, edit_ai_prompt, run_ai_scan	AI Visibility.
get_seo_visibility, add_tracked_keywords, run_seo_scan	SEO Visibility.
list_competitor_reports, get_competitor_report, create_competitor_report	Competitor reports.
keyword_research	Keyword metrics, ideas and who ranks.
site_explorer	Overview of any domain.
create_backlink_check, get_backlink_check	Backlink Checker.
search_goldmines, get_goldmines_domain, unlock_goldmines_sites	SEO Goldmines.
list_categories, list_countries	Reference lists.

Something missing? Tell us and we will look at it.