Ahrefs research and publisher recovery

An organization owner or admin connects Ahrefs in Settings → Integrations and accepts the versioned compliance, usage-cost and agent-access checkbox. API keys are masked, encrypted in the credential vault and never returned. Set a monthly API-unit cap; reaching it pauses API requests and notifies owners/admins. Reconnecting retains this month’s spend.

The eight MCP tools provide site overview, organic keywords, top pages, backlinks, referring domains, traffic history, batch domain lookups and publisher recovery. QA Commander/front desk uses the same authenticated service. Agent credentials cannot accept the owner checkbox.

For Chrome, sign in yourself, approve Ahrefs in Machines, acquire control and select the active report tab. For the desktop internal browser, enable the existing remote session for your named agent with signed-in browser permission for https://app.ahrefs.com. Select the desktop and its Ahrefs tab number in Integrations; hand control back to that agent. Desktop registration checks the person’s active session; subsequent reads require the agent’s current session grant and control lease. The connector never obtains cookies or passwords.

Browser reports return observed text and source URLs. Numeric history requires an explicitly labelled, visible ISO-date monthly Date/Month | Organic traffic table. Chart-only history is refused. Browser batch reads reuse the observed report URL’s domain target; live Ahrefs account compatibility is not yet verified.

Open Project → Publisher recovery, choose seeds or a niche, date bounds, sustained-decline threshold, pipeline and lead stage. Qualifying domains are ranked by lost traffic then decline percentage, and created in that project’s CRM pipeline with monthly evidence. Repeat runs update evidence without duplicating that project/domain. Desktop connections run the finder through the authorized agent; the web form cannot borrow an agent’s remote-session lease. Niche discovery uses API SERP data and requires API access.

This lane is awaiting review and deployment. Fixture acceptance does not claim that Paul’s account or production is connected.

Scheduled SEO checkups use the API connection. A browser connection needs the person's current control lease through the interactive Ahrefs tools. Revoked or stale consent, a paused/exhausted cap, a missing credential and a connection rotation return honest seo_not_connected evidence during a checkup; the run keeps its other evidence. Provider and database failures still surface as failures. Organization API keys need both write and marketing scopes for report and batch requests because these requests spend units; read-only keys can inspect connection status. Disconnect deletes the connector-held encrypted credential while retaining the consent receipt and usage history. Unknown transport outcomes retain reserved units and record an audit receipt with reservation_retained metering.

The tools are ahrefs_site_overview, ahrefs_organic_keywords, ahrefs_top_pages, ahrefs_backlinks, ahrefs_referring_domains, ahrefs_traffic_history, ahrefs_batch and ahrefs_publisher_recovery.

• API reference: current OpenAPI document.
• MCP tools: tool reference and access rules.
• Runbook: marketing workflows and recovery evidence.

Saved publisher assessments

The existing publisher-recovery entry records a dated assessment envelope for every run, including observed non-matches and unknown coverage. Provide requestId to replay that run without another provider call; a changed body with the same id is rejected. Current org consent is checked again on replay. Only observed sustained declines create project CRM leads.

Read project-scoped summaries with GET /v1/projects/{projectId}/ahrefs/publisher-recovery/assessments (limit 1–50 and opaque cursor), and evidence with GET /v1/projects/{projectId}/ahrefs/publisher-recovery/assessments/{assessmentId}. The Publisher recovery page displays saved windows, consecutive-month criteria, estimated monthly organic visitors, observed dates, unit usage and missing months. Monthly buckets overlap the supplied calendar-date window; they are not daily analytics. A missing requested month, stale final bucket, invalid history or unavailable plan never establishes a decline. Niche discovery also records empty/malformed rows and names domains omitted by the 50-site run budget, retaining actual units for partial discovery.

Assessment transport defaults off. GOODQA_PUBLISHER_ASSESS_TRANSPORT=recording only permits a synthetic HTTP provider at 127.0.0.1 through the existing GOODQA_SEO_PROVIDER_BASE_URL; saved results are explicitly labelled synthetic recordings. There is no live assessment transport in this component. Provider responses are capped at 256 KiB while streaming and monthly evidence at 25 rows. Existing org cap reservations, vault envelopes and agent-access consent remain the provider boundary. No crawling, outreach or recovery guarantee.

Local synthetic proof can be completed without an external account. An actual niche pilot remains MANUAL-PENDING: Paul or Eric supplies the Ahrefs account/key through the existing Integrations flow and accepts the current checkbox; a separately authorized live transport step is required. No new credential tool is needed.