MCP and API tool reference

Rewrite an existing article as a new draft revision (async → job_id; check with get_job, usually 1-3 minutes). scope: full (improve the whole article), sections (change only what the plan/instructions say, keep the rest) or meta (title, meta title and meta description only). Uses the refresh plan from plan_content_refresh and the project's brand, tone and linking rules; keeps images, videos and markdown structure, never invents links. The previous content is saved as a version first. Publishing stays separate: the live page is unchanged until the article is republished.

Build JSON-LD structured data for an article from its data (no AI): BlogPosting/Article with headline, description, image, dates, author and publisher, BreadcrumbList (when published), FAQPage (from an FAQ section) and VideoObject (from embedded YouTube videos). Saves it on the article in SEOForge and returns a ready <script> tag. SEOForge's publishing integrations don't output it yet, so add the tag to the page (or an SEO plugin) yourself.

Queries close to page 1 or the top 3 (average position ~8-20 with real impressions), ranked by clicks to gain at position 3. Each finding names the ranking page (and SEOForge article when it's ours); recommended_actions point to create_content_brief and update_article. From Search Console, no data cost.

Pages losing clicks or average position vs the previous period (or the same period last year), biggest loss first, with a likely cause (lost rankings, lower demand, lower CTR) and the queries that dropped. Refresh candidates → plan_content_refresh / refresh_article. From Search Console, no data cost.

Pages that get impressions but far fewer clicks than their positions usually earn (CTR-by-position curve), with the queries behind the gap. When a stored SERP exists for those queries, says whether AI Overviews, featured snippets, ads, local packs or shopping results likely explain it. Title/meta fixes → suggest_titles / update_article. From Search Console, no data cost.

Queries where two or more of our URLs each get a real share of impressions (they compete with each other), with severity and the page pairs that clash most → consolidation_plan. From Search Console, no data cost.

What it takes to rank for a keyword, and whether we can: intent, SERP features (AI Overview, featured snippet, People Also Ask...), dominant content type/format, typical word count of the top pages, each top-10 domain's strength vs ours, and a 0-100 rankability score with reasons. About $0.03-0.05 uncached (1 SERP, keyword metrics, backlink ranks, up to 10 page parses).

Brief for an article targeting a keyword, from the top-ranking pages: target length, outline (H2/H3 sections most top pages cover), terms they use, questions to answer (People Also Ask + question keywords), related keywords, and our articles to link to. Includes writer_notes ready for generate_article / add_content_plan_item.

Score one of our articles (0-100) against what ranks for its keyword: sections, terms and questions the top pages cover that it doesn't, and length vs the top pages. Builds the brief first (same cost as create_content_brief; cached). Fixes → update_article.

Group keywords that belong on the same page: keywords whose Google top 10 share at least `threshold` URLs. Each cluster has a primary keyword, total volume and the page to target (our ranking page, an existing article, a planned item, or new). One SERP per keyword (max 50, ~$0.002 each uncached); use dry_run first.

Which keywords first: opportunity score from volume × CTR gain at a reachable position × ease (difficulty vs our domain strength, current rankings from the rank tracker and Search Console) × intent fit. Returns estimated extra clicks per month per keyword.

Traffic you could get from ranking #1 for a keyword, beyond its own volume: estimated monthly organic traffic of the top-ranking page(s) across all their keywords, plus the parent topic (the top page's biggest keyword). 1 SERP + 1 ranked-keywords call per page.

What to write next: keyword ideas from seeds and/or the keyword gap vs competitors → drop what we already have or planned → prioritize → cluster (one item per cluster) → proposed plan items with title, type, supporting keywords, priority and dates. dry_run (default true) only proposes; dry_run: false adds them via add_content_plan_item (read & write key). Pass `items` from a dry run to add exactly those with no data cost. estimate_only returns the USD estimate without calling providers.

Which of our articles should link to a target article, with the anchor text and the sentence to put it in. Uses our articles' text and Search Console queries (target anchors, source page clicks). No data cost. Fixes → update_article on the source article.

Full map of a topic: keyword ideas clustered into pillar and supporting pages, which ones we rank for / have an article for / planned / miss, and how the top competitors cover them. Fetches max_serp SERPs (default 20); use dry_run first. Missing clusters → build_content_plan.

Keywords where we rank in the top 10 but don't own a SERP feature (featured snippet, People Also Ask, AI Overview citation, videos, images, top stories), with the format change that could win it. From stored SERPs for tracked and Search Console keywords (free); fetch_missing pulls fresh SERPs for keywords without one (costs, use dry_run).

Title and meta description options for a page, built from the queries it gets Search Console impressions for and the titles that rank for its top query. Shows which queries the current title misses. Feeds update_article (meta_title / meta_description).

Who the project really competes with in Google: domains ranking across its tracked and Search Console keywords (or, without keywords, organic competitors of its domain), split into business competitors and content sites (publishers, forums, directories/review sites, marketplaces, reference, social/video) with the signals behind each call. recommended_actions → keyword_gap, backlink_gap, broken_link_opportunities. DataForSEO Labs, ~$0.02.

Keywords competitors rank for that we don't (missing), or where a competitor is on page 1 well ahead of us (behind), scored 0-100 (volume, difficulty, how many competitors rank, intent) and grouped into topic clusters. Competitor-branded keywords are left out by default. recommended_actions → build_content_plan, add_content_plan_item, create_content_brief. DataForSEO Labs, one or two calls per competitor (dry_run for an estimate).

Link prospects: sites linking to competitors but not to us, ranked by authority, number of competitors they link to and spam score, labelled by site type (directory, publisher, blog...). recommended_actions → backlink_intersection (the exact linking pages). DataForSEO Backlinks, ~$0.03-0.08.

Pages that mention the brand but don't link to the project's site, by authority (negative or spammy mentions ranked lower) - the easiest link requests. Uses DataForSEO Content Analysis and Backlinks, ~$0.08. Outreach itself is manual.

Backlinks pointing at our broken (4xx/5xx) pages, grouped per broken URL with referring domains and anchors, plus a 301 redirect map to the closest live page (our articles and Search Console pages) so the links count again. Cross-checks the latest site audit's 4xx pages. DataForSEO Backlinks, ~$0.03.

Dead pages on competitor sites (4xx/5xx) that still have backlinks, re-checked through DataForSEO, with the topic to recreate, an archived copy link, our closest article, and the sites linking to them to contact. recommended_actions → add_content_plan_item / update_article, list_backlinks. DataForSEO Backlinks + On-Page, ~$0.05-0.2 (dry_run for an estimate).

What happened this week/month and what should we do? Search Console clicks and impressions vs the previous period, rank changes (entered/left top 10, biggest moves), Google Analytics sessions and key events, alerts, annotations, Google updates, striking-distance and declining pages, and the top 5 actions as tool calls. No data cost.

What to change in an article to win back or gain rankings: queries it lost and queries it gets but doesn't cover (Search Console), how the SERP changed since publishing (stored snapshots), sections / questions / terms the top results cover that it doesn't (create_content_brief), dated years and statistics, broken outbound links, and title/meta ideas. Saves the plan and returns refresh_plan_id for refresh_article. Paid parts (brief ~$0.02-0.03, link checks ~$0.000125 each) are cached; dry_run first.

Does an article show Google's quality signals? Checks author byline, sources cited, broken outbound links, internal links, freshness of dates and statistics, structure, readability (Flesch), image alt text, structured data and meta tags, on the SEOForge draft and (when published) the live page. Returns pass/warn/fail per check, a score, and fixes. Live page analysis and link checks cost ~$0.003 or less (cached).

Pages with almost no search traffic over 6+ months (Search Console, plus SEOForge articles Google never showed), each with a verdict: improve, merge (into a similar stronger page), redirect (similar page and it has backlinks) or noindex, and the reason. Uses internal links from the latest site audit when there is one; include_backlinks adds DataForSEO backlink counts (paid, dry_run first).

How to merge cannibalizing and weak pages: groups of pages (from find_cannibalization and find_zombie_pages, or the urls you pass), which page to keep, which to merge and 301 or to differentiate, a redirect map, and the queries and sections to carry over into the kept page (→ refresh_article). Backlinks per URL from DataForSEO (default on, ~$0.04; dry_run first).

Did our changes work? For article changes made through the API (update_article, refresh_article, generate_schema; see api_changes), compares the page's Search Console clicks, impressions and position in equal windows before and after the change went live (its next publish), relative to the whole site's trend, and summarizes which kinds of change pay off. Also shows site-wide before/after around annotations. Free.

Which articles and content types pay off? Per SEOForge article: Search Console clicks, traffic value (clicks × keyword CPC from DataForSEO, cached 30 days), Google Analytics organic sessions, key events and revenue, and ROI when you pass cost_per_article; plus totals per content type and topic. CPCs cost ~$0.01-0.08 uncached; dry_run first, or include_value: false for free data only.

Which pages aren't in Google, and why. Inspects a capped set of URLs with Search Console URL Inspection (URLs you pass, articles published in the last 30 days, pages that lost traffic, then top pages), and reports unindexed pages with Google's reason, Google-chosen canonical mismatches, sitemap URLs that redirect/404, sitemap errors and crawl-level redirects/non-indexable pages from the latest site audit. recommended_actions → submit_sitemap, internal_link_suggestions, update_article. Free (Search Console quota: 2,000 inspections/day, cached 3 days); dry_run previews the URL list.

Is internal linking helping the pages that matter? From the latest site audit joined with Search Console traffic: orphan pages, pages too many clicks deep, and pages with traffic (or SEOForge articles) that have few internal links, ranked by clicks. recommended_actions → internal_link_suggestions. Needs a site audit (start_site_audit); no extra data cost.

Which slow pages cost the most traffic. Checks the top pages by Search Console clicks against real-user Core Web Vitals (CrUX: LCP, INP, CLS), runs Lighthouse on failing or no-data pages, and returns failing pages ranked by clicks × severity, failing templates (by URL section) and the most common Lighthouse issues. Lighthouse runs are paid (~$0.004 each, capped by lab_pages); use dry_run for the estimate.

Is our schema markup valid, and which rich-result types are missing? Validates JSON-LD/microdata from the latest site audit and reads Google's detected rich results (URL Inspection) for a capped set of pages (URLs you pass, crawled pages with markup errors, recent SEOForge articles, top pages). Returns errors per page and expected-but-missing types (Article, author, BreadcrumbList, VideoObject, Organization) → generate_schema. Free.

Are language/country versions set up correctly? From the latest site audit's hreflang tags: invalid language/region codes, missing return links, hreflang pointing to redirected, broken or non-canonical URLs, missing self-references and conflicting codes. Needs a site audit (start_site_audit); no extra data cost.

Why did we move for this keyword? Compares the stored Google SERP before and after (who entered/left the top 10, new SERP features, our URL switching, how much the whole SERP moved) and lines it up with our change log, annotations, confirmed Google updates and backlink changes. Returns likely_causes and recommended_actions. Uses stored rank-tracker / serp_search snapshots (free); include_backlinks adds DataForSEO backlink history (~$0.04).

Is the whole SERP shaking (algorithm update) or just us? Volatility (0-100) per tracked keyword between consecutive weekly snapshots, by date and project-wide, with a verdict per keyword (serp_wide_move, just_us, ...) and overlapping Google updates. Free: uses stored rank-tracker snapshots.

How did a Google core/spam update affect us? Search Console clicks and positions in equal windows before the rollout and after it ended: verdict, winners and losers by page, by site section and by query type (branded, question, long/short tail), plus tracked keyword moves. Defaults to the latest confirmed core update (list_google_updates). No data cost.

What are competitors publishing, and is it ranking? Per competitor (project competitors or the ones given, max 5): pages that newly entered their top pages by traffic since the last run, pages gaining keywords, and newly ranking keywords, flagged when our content plan or articles already cover them. Stores a snapshot each run (first run = baseline). DataForSEO Labs, ~$0.03 per competitor; dry_run shows the estimate.

Which technical issues matter most? Takes the latest site audit's issues (start_site_audit) and ranks them by the Search Console clicks and impressions of the pages they affect, with the top affected pages and the tool to fix each.

Add a dated note to the project's timeline (e.g. 'migrated to new theme', 'started link campaign') so explain_rank_change, algorithm_update_impact and project_report can take it into account.

Notes on the project's timeline, newest first; optionally with the API change log and Google updates in the same range.

Create an alert rule, checked after each data refresh (hourly). Types: clicks_drop (Search Console clicks in the last 7 days fell by at least threshold % vs the 7 days before; default 20 percent); rank_drop (A tracked keyword lost at least threshold positions (or fell out of the top 100) in its latest check; default 5 positions); keyword_lost_top10 (At least threshold tracked keywords left the top 10 in their latest check; default 1 keywords); new_lost_backlinks (Referring domains changed by at least threshold (gained or lost) between the last two backlink snapshots; default 5 referring domains); indexing_issue (The latest site audit has at least threshold more pages with critical issues (broken, 4xx/5xx, non-indexable, redirect loops) than the previous one; default 1 pages). Delivered by email (to a project member), Slack incoming webhook or a JSON webhook (public https only).

The project's alert rules (targets masked) and the available alert types.

Delete an alert rule (its past events are deleted with it).

Alerts that fired, newest first, with details and delivery status.

Send project_report every week (Mondays) or month (the 1st), after 08:00 UTC, by email (to a project member), Slack incoming webhook or a JSON webhook.

The project's scheduled reports (targets masked), with when each was last sent and any delivery error.

Stop and delete a scheduled report.

Confirmed Google Search ranking updates (core and spam) from the Google Search Status Dashboard, newest first, with rollout start/end. Use an id with algorithm_update_impact.

Google's view of one of the project's URLs (Search Console URL Inspection): indexed or not and why, last crawl, Google-chosen vs declared canonical, rich results detected. Cached for 3 days; Google allows 2,000 inspections per property per day.

Sitemaps Google Search Console knows for the project: last submitted and downloaded, errors, warnings and URL counts.

Submit or resubmit a sitemap to Google Search Console so Google recrawls it (e.g. after publishing or updating articles). Needs a read & write API key.

Real-user Core Web Vitals (LCP, INP, CLS, plus FCP and TTFB) at the 75th percentile from the Chrome UX Report, for a URL or a whole origin (default: the project's site), optionally with up to 40 weekly points. Falls back to Lighthouse lab data when there's no real-user data.

Live search results for one keyword, normalized across engines: position, type, URL, domain, title, snippet, plus SERP features (featured snippet, People Also Ask, AI Overview with cited URLs, local pack, videos, images, top stories, ads count). With a project, the SERP is saved for serp_history. Google shopping/videos come from serper.dev.

Search results for up to 100 keywords at once in DataForSEO's cheaper queued mode (async). Returns a job_id; get_job returns per-keyword top results and SERP features when ready (usually a few minutes). Use dry_run first to see the cost.

Past SERPs for a keyword: the project's stored snapshots (rank tracker checks and serp_search results, free) and/or DataForSEO Labs Google history (~12 months, paid). Each snapshot has the top results, our position and SERP features.

Google autocomplete suggestions for a keyword (DataForSEO, or serper.dev).

Details, subtitles (transcript text) or comments for one YouTube video.

Search volume, 12-month trend, CPC, competition, keyword difficulty, intent and average backlinks of the top 10 for up to 700 keywords. Google via DataForSEO Labs (or fresh Google Ads volume with source google_ads); Bing via Bing Ads.

Keyword ideas from seed keywords with metrics. mode: ideas (same topic, up to 200 seeds), suggestions (contain the seed), related (Google 'related searches'), questions (question phrasing). Filter by min_volume / max_difficulty.

Keywords relevant to a domain or URL, with metrics. Google via Labs (domain) or Google Ads (domain or page); Bing via Bing Ads.

Interest over time (0-100) for up to 5 keywords, optionally by region, related queries (Google Trends, one keyword) or age/gender (DataForSEO Trends). Use location 'worldwide' for global data.

Monthly history of Google search volume, CPC and competition for a keyword (DataForSEO Labs).

Organic overview of a domain in Google: ranking keyword count, estimated monthly traffic (etv) and its value, position distribution and keyword movement. Defaults to the project's domain.

Monthly history of a domain's organic keywords, estimated traffic, top-3 and top-10 counts in Google.

Keywords a domain or URL ranks for in Google, with position, ranking URL, volume, CPC, difficulty, intent and estimated traffic. Filter by position, volume, intent or text.

A domain's pages (or subdomains) ranked by estimated organic traffic from Google, with keyword counts and top-10 rankings.

Organic search competitors: for a domain (domains sharing its Google keywords), or for a set of keywords (domains ranking across them). Give `keywords` to use keyword mode; otherwise uses `domain` (default: the project's domain).

Keywords shared by domains (mode shared), or a keyword gap (mode gap: keywords the other domains rank for and the first domain doesn't). Put your own domain first. One provider call per extra domain (max 6 domains).

Keywords several URLs rank for together (mode shared), or keywords competitor URLs rank for and the first URL doesn't (mode gap). Absolute URLs; a trailing /* matches a URL prefix.

Estimated Google organic traffic for up to 1,000 domains or URLs at once, now or by month (historical: domains only, from Oct 2020).

Backlink profile of a domain or URL: backlinks, referring domains/IPs/subnets, rank, spam score, broken backlinks, top TLDs and countries.

Individual backlinks to a domain or URL: linking page, target URL, anchor, dofollow, ranks, spam score, first/last seen. Filter by dofollow, new/lost, anchor text, broken targets.

Domains linking to a domain or URL, with their rank, backlink count, spam score and first seen / lost dates.

Anchor text distribution of a domain's or URL's backlinks: referring domains and backlinks per anchor.

Backlinks and referring domains over time with new vs lost counts, for a domain. group: day, week, month (default) or year. source history = monthly snapshots since 2019 with rank.

Domains whose backlink profiles overlap with the target's (shared referring domains), with their rank.

Referring domains (level domain) or pages (level page) that link to several targets, optionally excluding ones that already link to exclude_target (usually your own domain). The basis for link prospecting.

Rank, backlinks, referring domains, spam score and new/lost counts for up to 1,000 domains or URLs (one provider call per metric). Rows are paged with limit/offset.

Parse one web page (any site): status, title, meta description, canonical, headings outline, word count, internal/external links, image alt coverage, structured data presence and on-page issues. Fetched by DataForSEO.

Crawl a site (default: the project's website) and check every page for technical SEO issues. Async: returns a job_id; poll get_job, then use get_site_audit, list_audit_issues and list_audit_pages. Use dry_run to see the estimated cost first.

Summary of the project's latest site audit (or a given one): crawl progress, site checks (SSL, sitemap, robots.txt), on-page score and issue counts.

Issues found by the latest site audit, most severe first, with the number of affected pages. Pass `issue` (a name from this list, e.g. no_title, duplicate_title, broken_links, non_indexable, redirect_chain, is_orphan_page) to list the affected pages.

Pages crawled by the latest site audit with status code, click depth and internal links in/out. Filter by status or depth; sort to find orphan or deep pages.

Web pages (news, blogs, forums, ...) that mention a brand or keyword, with domain rank, snippet, date and sentiment. Defaults to the project's name.

How do we rank on Google Maps across a city? Checks the Maps results at a grid of points around a centre (3×3, 5×5 or 7×7, spacing_km apart): rank per point, average rank, where we're in the top 3 and the top competitors. dry_run is true by default and returns the cost (~$0.002 per point); pass dry_run=false to run.