ahrefs

Ahrefs

Ahrefs is a popular SEO tool suite used by marketers and SEO professionals. It helps users analyze website backlinks, keywords, and overall search engine performance.

Official docs: https://ahrefs.com/api/documentation/v3

Ahrefs Overview

• Site Explorer
• Overview — Provides a general overview of a website's SEO performance.
• Referring domains — Shows domains that link to the target website.
• Referring pages — Shows specific pages that link to the target website.
• Organic keywords — Lists keywords for which the target website ranks in organic search.
• Top pages — Identifies the pages on the target website with the most organic traffic.
• Content gap — Finds keywords that competitors rank for, but the target website doesn't.
• Backlinks — Displays the backlinks pointing to the target website.
• Anchors — Shows the anchor text used in backlinks.
• Broken backlinks — Identifies broken backlinks pointing to the target website.
• Outgoing links — Lists the links that the target website points to.
• Paid keywords — Lists keywords for which the target website advertises.
• Ads positions — Shows the ad positions for the target website.
• Pages — Lists the pages on the target website.
• Traffic share — Shows the distribution of traffic to the target website.
• Keywords Explorer
• Overview — Provides a general overview of a keyword's SEO performance.
• Matching terms — Shows keywords that are similar to the target keyword.
• Search suggestions — Provides suggestions for related keywords.
• Questions — Lists questions related to the target keyword.
• Related keywords — Shows keywords that are related to the target keyword.
• Also rank for — Lists keywords that the top-ranking pages for the target keyword also rank for.
• Ranking history — Shows the ranking history of the target keyword.
• Batch Analysis — Allows analyzing multiple websites at once.
• Domain Comparison — Allows comparing multiple websites side-by-side.
• Content Explorer
• Overview — Provides a general overview of a content topic's SEO performance.
• Matching terms — Shows content topics that are similar to the target content topic.
• Referring domains — Shows domains that link to content about the target content topic.
• Top pages — Identifies the pages about the target content topic with the most organic traffic.
• SEO Toolbar
• Get SEO Metrics — Retrieves SEO metrics for the current page.

Working with Ahrefs

This skill uses the Membrane CLI to interact with Ahrefs. Membrane handles authentication and credentials refresh automatically — so you can focus on the integration logic rather than auth plumbing.

Install the CLI

Install the Membrane CLI so you can run membrane from the terminal:

npm install -g @membranehq/cli@latest

Authentication

membrane login --tenant --clientName=<agentType>

This will either open a browser for authentication or print an authorization URL to the console, depending on whether interactive mode is available.

Headless environments: The command will print an authorization URL. Ask the user to open it in a browser. When they see a code after completing login, finish with:

membrane login complete <code>

Add --json to any command for machine-readable JSON output.

Agent Types : claude, openclaw, codex, warp, windsurf, etc. Those will be used to adjust tooling to be used best with your harness

Connecting to Ahrefs

Use membrane connection ensure to find or create a connection by app URL or domain:

membrane connection ensure "https://ahrefs.com" --json

The user completes authentication in the browser. The output contains the new connection id.

This is the fastest way to get a connection. The URL is normalized to a domain and matched against known apps. If no app is found, one is created and a connector is built automatically.

If the returned connection has state: "READY", skip to Step 2.

1b. Wait for the connection to be ready

If the connection is in BUILDING state, poll until it's ready:

npx @membranehq/cli connection get <id> --wait --json

The --wait flag long-polls (up to --timeout seconds, default 30) until the state changes. Keep polling until state is no longer BUILDING.

The resulting state tells you what to do next:

• READY — connection is fully set up. Skip to Step 2.
• CLIENT_ACTION_REQUIRED — the user or agent needs to do something. The clientAction object describes the required action:
• clientAction.type — the kind of action needed:
• "connect" — user needs to authenticate (OAuth, API key, etc.). This covers initial authentication and re-authentication for disconnected connections.
• "provide-input" — more information is needed (e.g. which app to connect to).
• clientAction.description — human-readable explanation of what's needed.
• clientAction.uiUrl (optional) — URL to a pre-built UI where the user can complete the action. Show this to the user when present.
• clientAction.agentInstructions (optional) — instructions for the AI agent on how to proceed programmatically.

After the user completes the action (e.g. authenticates in the browser), poll again with membrane connection get <id> --json to check if the state moved to READY.

• CONFIGURATION_ERROR or SETUP_FAILED — something went wrong. Check the error field for details.

Searching for actions

Search using a natural language description of what you want to do:

membrane action list --connectionId=CONNECTION_ID --intent "QUERY" --limit 10 --json

You should always search for actions in the context of a specific connection.

Each result includes id, name, description, inputSchema (what parameters the action accepts), and outputSchema (what it returns).

Popular actions

| Name | Key | Description | | --- | --- | --- | | Get Extended Metrics | get-extended-metrics | Get extended SEO metrics including referring domains count, referring class C networks, and referring IP addresses. | | Get Pages | get-pages | Get a list of crawled pages on the target domain with their basic information. | | Get Subscription Info | get-subscription-info | Get information about your Ahrefs API subscription including usage and limits. | | Get Positions Metrics | get-positions-metrics | Get estimated organic traffic metrics including number of keywords, estimated traffic, and traffic cost. | | Get Ahrefs Rank | get-ahrefs-rank | Get the Ahrefs Rank (global ranking based on backlink profile strength) for URLs on the target domain. | | Get New and Lost Backlinks | get-new-lost-backlinks | Get new or lost backlinks for a target with details of the referring pages. | | Get Linked Domains | get-linked-domains | Get domains that the target links out to. | | Get Broken Backlinks | get-broken-backlinks | Get broken backlinks pointing to the target (pages that return 4xx/5xx errors). | | Get Anchors | get-anchors | Get anchor text analysis showing the text used in backlinks to the target, along with backlink and referring domain c... | | Get Referring Domains | get-referring-domains | Get the list of referring domains that contain backlinks to the target, with details like domain rating and backlink ... | | Get Metrics | get-metrics | Get SEO metrics for a target including total backlinks, referring pages, dofollow/nofollow counts, and more. | | Get Backlinks | get-backlinks | Get backlinks pointing to a target URL or domain with details of the referring pages including anchor text, page titl... | | Get Domain Rating | get-domain-rating | Get the Domain Rating (DR) and Ahrefs Rank of a domain. |

Running actions

membrane action run <actionId> --connectionId=CONNECTION_ID --json

To pass JSON parameters: