ahrefs

What this skill does

# 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:

```bash
npm install -g @membranehq/cli@latest
```

### Authentication

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

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

To pass JSON parameters: